# المراجع

المراجع هي مؤشرات مسماة إلى الالتزامات. الفروع والعلامات وHEAD ومراجع تتبع الفروع البعيدة كلها مراجع. يقرأ Pitmaster المراجع من الملفات المنفصلة وpacked-refs وreftable، ويكتب الملفات المنفصلة وpacked-refs.

## RefDatabase

`RefDatabase` هي الطبقة المركبة التي تبحث أولًا عن المراجع المنفصلة، ثم في reftable (عندما يحتوي المستودع عليها)، ثم في packed-refs.

```php
use Pitmaster\Ref\RefDatabase;

$refs = new RefDatabase($gitDir, $commonDir);

// Resolve a ref to an ObjectId
$id = $refs->resolve('refs/heads/main');

// Resolve HEAD (follows symbolic refs)
$headId = $refs->resolveHead();

// Read HEAD as a symbolic ref (null when HEAD is detached)
$symref = $refs->readHead();
echo $symref?->target;  // 'refs/heads/main'

// List all refs
foreach ($refs->list() as $name => $id) {
    echo "{$id->hex} {$name}\n";
}

// Update a ref
$refs->update('refs/heads/main', $newCommitId);

// Delete a ref
$refs->delete('refs/heads/old-branch');
```

في أشجار العمل المرتبطة، يحتفظ `RefDatabase` بـ HEAD والمراجع الزائفة الأخرى الخاصة بكل شجرة عمل (`ORIG_HEAD`، `MERGE_HEAD`، `CHERRY_PICK_HEAD`، `REVERT_HEAD`، `REBASE_HEAD`، `BISECT_HEAD`) في مجلد git الخاص بشجرة العمل. تُكتب الفروع والوسوم وإدخالات `refs/` الأخرى في المجلد المشترك، ويُقرأ `packed-refs` دائمًا من المجلد المشترك.

## المراجع المنفصلة

المراجع المنفصلة ملفات فردية في `.git/refs/`. يحتوي كل ملف على تجزئة سداسية عشرية للكائن المستهدف (40 حرفًا، أو 64 لـSHA-256)، تليها سطر جديد.

```
.git/refs/heads/main           -> abc123def456...\n
.git/refs/tags/v1.0.0          -> 789012abc345...\n
.git/refs/remotes/origin/main  -> abc123def456...\n
```

```php
use Pitmaster\Ref\LooseRefStore;

$store = new LooseRefStore($gitDir, $commonDir); // $commonDir defaults to $gitDir

$id = $store->resolve('refs/heads/main');
$store->update('refs/heads/main', $commitId);
$store->delete('refs/heads/old');
```

### HEAD

HEAD مرجع خاص يمكن أن يكون إما:

**رمزيًا**: يشير إلى مرجع آخر (وهو الأكثر شيوعًا عند العمل على فرع):
```
ref: refs/heads/main\n
```

**منفصلًا**: يشير مباشرةً إلى تجزئة التزام:
```
abc123def456789012abc345def678901234abcd\n
```

```php
use Pitmaster\Ref\SymbolicRef;

$symref = SymbolicRef::parse('HEAD', $headContent);

if ($symref !== null) {
    echo "On branch: {$symref->target}\n";
    // 'refs/heads/main'
} else {
    echo "Detached HEAD\n";
}
```

## المراجع المجمّعة

يجمع ملف `packed-refs` مراجع كثيرة في ملف واحد لتحسين الكفاءة. ينشئه Git أثناء `git pack-refs` أو `git gc`.

```
# pack-refs with: peeled fully-peeled sorted
abc123def456789012abc345def678901234abcd refs/heads/main
789012abc345def678901234abcdabc123def456 refs/tags/v1.0.0
^def456789012abc345def678901234abcdabc12
```

الأسطر التي تبدأ بـ`^` هي قيم مقشّرة: الالتزام الذي تشير إليه العلامة المشروحة في النهاية.

```php
use Pitmaster\Ref\PackedRefStore;

$store = new PackedRefStore($commonDir);

$id = $store->resolve('refs/heads/main');

foreach ($store->list() as $name => $id) {
    echo "{$id->hex} {$name}\n";
}
```

### القيم المقشّرة

قد يتضمن ملف packed-refs للعلامات المشروحة القيمة المقشّرة (المفكوك مرجعها) في السطر التالي لمرجع العلامة. والقيمة المقشّرة هي الالتزام الذي يشير إليه كائن العلامة في النهاية (عبر كائنات علامات متعددة محتملة).

```php
$peeled = $store->peeled('refs/tags/v1.0.0');
// Returns the commit ObjectId, or null if not peeled
```

## ترتيب حل المراجع

عند حل مرجع، يتحقق Pitmaster بالترتيب التالي:

1. مرجع منفصل (ملف في `.git/refs/`)
2. Reftable، عند وجود `.git/reftable/tables.list`
3. مرجع مجمّع (مدخل في `.git/packed-refs`)

للمراجع المنفصلة الأولوية. عند تحديث مرجع مجمّع، تُكتب القيمة الجديدة كمرجع منفصل (ولا يُعاد كتابة ملف packed-refs). يؤدي حذف مرجع إلى إزالة الملف المنفصل والمدخل المجمّع. يعيد `$repo->packRefs()` كتابة `packed-refs` من المراجع الحالية ويزيل الملفات المنفصلة.

## SymbolicRef

المراجع الرمزية هي مراجع تشير إلى مراجع أخرى بدلًا من الإشارة مباشرةً إلى كائنات.

```php
use Pitmaster\Ref\SymbolicRef;

// Parse
$ref = SymbolicRef::parse('HEAD', "ref: refs/heads/main\n");
echo $ref->name;    // 'HEAD'
echo $ref->target;  // 'refs/heads/main'

// Update
$refs->updateSymbolic('HEAD', 'refs/heads/feature');
```

## Reflog

يسجل سجل المراجع أوقات تغيير المراجع، مما يتيح لـ`git reflog` عرض سجل HEAD ورؤوس الفروع.

توجد ملفات Reflog في `.git/logs/`:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

يسجل كل سطر ما يلي:
```
<old-hash> <new-hash> <author> <timestamp> <tz>\t<message>
```

```php
use Pitmaster\Ref\Reflog;

$reflog = Reflog::open($gitDir, 'HEAD');

// Read entries
$entries = $reflog->entries();
foreach ($entries as $entry) {
    echo "{$entry['old']} -> {$entry['new']}: {$entry['message']}\n";
}

// Append an entry
$reflog->append(
    $oldId,
    $newId,
    'Name <email> 1700000000 +0000',
    'commit: Add feature',
);
```

يستخدم stash سجل مراجع `refs/stash` لتخزين مكدسه.

## Reftable

Reftable تنسيق ثنائي أحدث لتخزين المراجع، صُمم لتحسين الأداء عند وجود مراجع كثيرة (آلاف الفروع). وهو يحل محل المراجع المنفصلة وpacked-refs.

تُخزّن ملفات Reftable في `.git/reftable/` وتحتوي على:
- سجلات المراجع (مرتبة حسب الاسم)
- سجلات السجل (مدخلات سجل المراجع)
- فهرسة على مستوى الكتل للبحث السريع

يقرأ Pitmaster سجلات المراجع من ملفات reftable عند وجودها؛ ولا تُقرأ سجلات السجل. عند وجود reftable، تحل محل `packed-refs` لأغراض العرض. تُكتب تحديثات المراجع دائمًا كملفات منفصلة، ولا يقرأها git في مستودع reftable، لذا تعامل مع مستودعات reftable على أنها للقراءة فقط.

## اصطلاحات تسمية المراجع

| النمط | المعنى |
|---------|---------|
| `refs/heads/<name>` | فرع محلي |
| `refs/tags/<name>` | وسم (خفيف أو مشروح) |
| `refs/remotes/<remote>/<name>` | فرع تتبّع بعيد |
| `refs/stash` | مكدس الإيداع المؤقت |
| `refs/notes/<namespace>` | ملاحظات Git |
| `HEAD` | عملية السحب الحالية (رمزية أو منفصلة) |
| `FETCH_HEAD` | نتيجة آخر جلب (كتبتها git؛ لا تكتبها Pitmaster عند تنفيذ `fetch()`) |
| `MERGE_HEAD` | الفرع الجاري دمجه (أثناء الدمج) |
| `ORIG_HEAD` | HEAD السابقة (قبل العمليات الخطرة) |

## العمل مع المراجع عبر Repository

```php
// Read
$branch = $repo->branch();          // Current branch name
$branches = $repo->branches();      // All branch names
$tags = $repo->tags();              // All tag names
$refs = $repo->allRefs();           // All refs as name => hash

// Write
$repo->createBranch('feature');     // Create refs/heads/feature
$repo->deleteBranch('feature');     // Delete refs/heads/feature
$repo->createTag('v1.0', 'Release');// Create annotated tag
$repo->createLightweightTag('v1.0-lite'); // Create lightweight tag
$repo->updateRef('refs/heads/main', $id); // Direct ref update

// Resolve
$id = $repo->resolve('HEAD');
$id = $repo->resolve('main');
$id = $repo->resolve('v1.0.0');
$id = $repo->resolve('HEAD~3');
```