Состояние

Pitmaster вычисляет состояние рабочего дерева, сравнивая три состояния: дерево коммита HEAD, индекс (область подготовки) и рабочее дерево (фактические файлы на диске). CLI выводит краткую сводку в стиле git status, а statusPorcelainV2() выводит формат porcelain v2 для git.

Базовое использование

$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:

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

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:

echo $repo->statusPorcelainV2();

Вывод:

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

Сначала идут отслеживаемые записи, затем неотслеживаемые. Переименования выводятся строками 2, а конфликты — строками u. Заголовки # branch из git status --porcelain=v2 --branch не выводятся, а игнорируемые файлы не перечисляются.

Как вычисляется состояние

Класс WorkingTreeStatus выполняет трехстороннее сравнение:

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, чтобы определить, какие неотслеживаемые файлы следует считать игнорируемыми, а какие — неотслеживаемыми.

use Pitmaster\Status\GitIgnore;

Класс GitIgnore разбирает шаблоны gitignore из:

• .gitignore в корне репозитория
• .gitignore в подкаталогах
• .git/info/exclude

Поддерживается следующий синтаксис шаблонов:

• Шаблоны glob (*.log, build/)
• Отрицание (!important.log)
• Шаблоны только для каталогов (с завершающим /)
• Начальный / для шаблонов относительно корня
• ** для рекурсивного сопоставления

Категоризация записей состояния

Типичный шаблон для отображения UI:

$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

./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 включает помощник для протокола fsmonitor в git:

use Pitmaster\Status\Fsmonitor;

Класс Fsmonitor может обращаться к хуку core.fsmonitor (при сбое выполняется проверка времени изменения), чтобы узнать, какие файлы изменились после заданного токена. Для дескрипторов, открытых с ['processes' => false], он отключается. Сейчас status() не вызывает его, а напрямую сравнивает данные stat и содержимое.