# 状態

Pitmasterは3つの状態、すなわち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`クラスは次の3方向比較を実行します:

```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 データと内容を直接比較します。