# الحالة

تحسب 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`. لا تُطبع ترويسات `# branch` الخاصة بـ `git status --porcelain=v2 --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 أداة مساعدة لبروتوكول fsmonitor في git:

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

يمكن للفئة `Fsmonitor` الاستعلام عن خطاف `core.fsmonitor` (مع الرجوع إلى فحص أوقات التعديل) لمعرفة الملفات التي تغيرت منذ رمز مميز. وتعطّل نفسها عند فتح المقابض باستخدام `['processes' => false]`. لا تستدعيها `status()` حاليًا؛ إذ تقارن بيانات stat والمحتوى مباشرة.