# 状态

Pitmaster 通过比较三种状态来计算工作树状态：HEAD 提交的树、索引（暂存区）和工作树（磁盘上的实际文件）。CLI 会据此打印 `git status` 风格的摘要，而 `statusPorcelainV2()` 会打印 git 的 porcelain v2 格式。

## 基本用法

```php
$entries = $repo->status();

foreach ($entries as $entry) {
    echo $entry->shortFormat() . "\n";
}
```

`shortFormat()` 会打印 git 的简短格式：

```
M  src/Modified.php          (staged modification)
 M src/WorktreeModified.php  (unstaged modification)
A  src/NewFile.php           (staged new file)
 D src/Deleted.php           (deleted in worktree)
?? untracked.txt             (untracked file)
```

## StatusEntry

每个文件的状态都用一个 `StatusEntry` 表示：

```php
use Pitmaster\Status\StatusEntry;

$entry->path;       // File path relative to repo root
$entry->index;      // FileStatus: HEAD-to-index state
$entry->worktree;   // FileStatus: index-to-worktree state
$entry->origPath;   // Original path for renamed entries, otherwise null
$entry->renameScore; // Similarity score for renamed entries, otherwise null
$entry->shortFormat(); // "XY path", "?? path", or "R  old -> new"
```

## FileStatus 枚举

```php
use Pitmaster\Status\FileStatus;

FileStatus::Added;      // 'A' - new file
FileStatus::Modified;   // 'M' - content changed
FileStatus::Deleted;    // 'D' - file removed
FileStatus::Renamed;    // 'R' - file renamed
FileStatus::Copied;     // 'C' - file copied
FileStatus::Unmerged;   // 'U' - unresolved merge conflict
FileStatus::Untracked;  // '?' - not in index
FileStatus::Ignored;    // '!' - matched by .gitignore
FileStatus::Unmodified; // ' ' - no change
```

`status()` 不会报告被忽略的文件，因此其结果中不会出现 `Ignored`。

## Porcelain v2 输出

如需与 `git status --porcelain=v2` 匹配的机器可读状态输出：

```php
echo $repo->statusPorcelainV2();
```

输出：

```
1 .M N... 100644 100644 100644 ce013625030ba8dba906f756967f9e9ca394464a ce013625030ba8dba906f756967f9e9ca394464a modified-file.txt
? untracked-file.txt
```

先列出已跟踪条目，再列出未跟踪条目。重命名使用 `2` 行，冲突使用 `u` 行。不会打印 `git status --porcelain=v2 --branch` 的 `# branch` 标头，也不会列出被忽略的文件。

## 状态的计算方式

`WorkingTreeStatus` 类执行三方比较：

```php
use Pitmaster\Status\WorkingTreeStatus;

$status = new WorkingTreeStatus($repo->objectDatabase(), $repo->workDir(), $repo->gitDir());
$entries = $status->compute($repo->index(), $repo->resolve('HEAD'));
```

### 步骤 1：构建 HEAD 树映射

将 HEAD 提交的树展平为 `path => blob hash` 映射。这代表最近一次提交的状态。

### 步骤 2：比较 HEAD 与索引

对 HEAD 树和索引中的每个文件：
- 在 HEAD 中但不在索引中：索引列为 `Deleted`
- 在索引中但不在 HEAD 中：索引列为 `Added`
- 两者都有但哈希值不同：索引列为 `Modified`
- 两者都有且哈希值相同：索引列为 `Unmodified`

### 步骤 3：比较索引与工作树

对索引和工作树中的每个文件：
- 在索引中但磁盘上不存在：工作树列为 `Deleted`
- 两者都有但内容不同：工作树列为 `Modified`
- 两者都有且内容一致：工作树列为 `Unmodified`

### 步骤 4：检测未跟踪文件

遍历工作树目录，跳过 `.git/` 和被忽略的路径，并将索引中不存在的文件在两列中都报告为 `Untracked`。

## .gitignore 支持

Pitmaster 会解析 `.gitignore` 文件，以确定哪些未跟踪文件应报告为已忽略或未跟踪。

```php
use Pitmaster\Status\GitIgnore;
```

`GitIgnore` 类会从以下位置解析 gitignore 模式：
- 仓库根目录中的 `.gitignore`
- 子目录中的 `.gitignore`
- `.git/info/exclude`

支持的模式语法：
- Glob 模式（`*.log`、`build/`）
- 取反（`!important.log`）
- 仅匹配目录的模式（以 `/` 结尾）
- 根目录相对模式前的 `/`
- 用于递归匹配的 `**`

## 状态条目的分类

UI 显示的一种常见模式：

```php
$staged = [];
$unstaged = [];
$untracked = [];

foreach ($repo->status() as $entry) {
    if ($entry->index === FileStatus::Untracked) {
        $untracked[] = $entry;
    } elseif ($entry->index !== FileStatus::Unmodified) {
        $staged[] = $entry;
    }

    if ($entry->worktree !== FileStatus::Unmodified
        && $entry->index !== FileStatus::Untracked
    ) {
        $unstaged[] = $entry;
    }
}
```

## CLI 用法

```bash
./vendor/bin/pitmaster status
```

输出：

```
On branch main

Changes to be committed:
	new file:   src/Feature.php

Changes not staged for commit:
	modified:   src/Existing.php

Untracked files:
	notes.txt
```

## 文件系统监视器

Pitmaster 包含一个用于 git fsmonitor 协议的辅助工具：

```php
use Pitmaster\Status\Fsmonitor;
```

`Fsmonitor` 类可以查询 `core.fsmonitor` 钩子（如果不可用则扫描修改时间），以了解自某个令牌以来哪些文件发生了更改。对于使用 `['processes' => false]` 打开的句柄，它会自行关闭。`status()` 目前不会调用它；它会直接比较 stat 数据和内容。