# Ref'ler

Ref'ler (referanslar), commit'lere işaret eden adlandırılmış işaretçilerdir. Dallar, tag'ler, HEAD ve uzak izleme ref'lerinin tümü ref'tir. Pitmaster ref'leri gevşek dosyalardan, packed-refs ve reftable'dan okur; gevşek dosyalara ve packed-refs'e yazar.

## RefDatabase

`RefDatabase`, önce gevşek ref'leri, ardından reftable'ı (depoda varsa), sonra packed-refs'i arayan bileşik katmandır.

```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');
```

Bağlantılı çalışma ağaçlarında `RefDatabase`, HEAD'i ve çalışma ağacına özgü diğer sözde ref'leri (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) çalışma ağacına özgü git dizininde tutar. Dallar, tag'ler ve diğer `refs/` girdileri ortak dizine yazılır; `packed-refs` ise her zaman ortak dizinden okunur.

## Gevşek ref'ler

Gevşek ref'ler, `.git/refs/` içindeki ayrı dosyalardır. Her dosya, hedef nesnenin onaltılık özetini (40 karakter veya SHA-256 için 64 karakter) ve ardından satır sonunu içerir.

```
.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, şu biçimlerden birini alabilen özel bir ref'tir:

**Sembolik**: başka bir ref'e işaret eder (bir daldayken en yaygın biçim):
```
ref: refs/heads/main\n
```

**Ayrık**: doğrudan bir commit özetine işaret eder:
```
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";
}
```

## Paketlenmiş ref'ler

`packed-refs` dosyası, verimlilik için birçok ref'i tek bir dosyada birleştirir. Git bunu `git pack-refs` veya `git gc` sırasında oluşturur.

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

`^` ile başlayan satırlar, açıklamalı bir tag'in sonunda işaret ettiği commit olan soyulmuş değerlerdir.

```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";
}
```

### Soyulmuş değerler

Açıklamalı tag'lerde packed-refs dosyası, tag ref'inden sonraki satıra soyulmuş (başvurusu çözümlenmiş) değeri ekleyebilir. Soyulmuş değer, tag nesnesinin (birden çok tag nesnesi üzerinden) sonunda işaret ettiği commit'tir.

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

## Ref çözümleme sırası

Bir ref çözümlenirken Pitmaster şu sırayla kontrol eder:

1. Gevşek ref (`.git/refs/` içindeki dosya)
2. Reftable, `.git/reftable/tables.list` mevcutsa
3. Paketlenmiş ref (`.git/packed-refs` içindeki girdi)

Gevşek ref'lere öncelik verilir. Paketlenmiş bir ref güncellendiğinde yeni değer gevşek ref olarak yazılır (packed-refs dosyası yeniden yazılmaz). Bir ref silindiğinde hem gevşek dosya hem de paketlenmiş girdi kaldırılır. `$repo->packRefs()` geçerli ref'lerden `packed-refs` dosyasını yeniden yazar ve gevşek dosyaları kaldırır.

## SymbolicRef

Sembolik ref'ler, doğrudan nesnelere değil başka ref'lere işaret eden referanslardır.

```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

Reflog, ref'lerin ne zaman değiştiğini kaydeder; böylece `git reflog`, HEAD'in ve dal uçlarının geçmişini gösterebilir.

Reflog dosyaları `.git/logs/` içinde bulunur:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

Her satır şunları kaydeder:
```
<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, yığın depolaması olarak `refs/stash`'in reflog'unu kullanır.

## Reftable

Reftable, çok sayıda ref'in (binlerce dalın) daha iyi performansla saklanması için tasarlanmış daha yeni bir ikili biçimdir. Hem gevşek ref'lerin hem de packed-refs'in yerini alır.

Reftable dosyaları `.git/reftable/` içinde saklanır ve şunları içerir:
- Ref kayıtları (ada göre sıralanmış)
- Günlük kayıtları (reflog girdileri)
- Hızlı aramalar için blok düzeyinde dizinleme

Pitmaster, varsa reftable dosyalarının ref kayıtlarını okur; günlük kayıtları okunmaz. Bir reftable bulunduğunda listeleme için `packed-refs`'in yerini alır. Ref güncellemeleri her zaman gevşek dosyalara yazılır; ancak git bunları reftable deposunda okumaz. Bu nedenle reftable depolarını salt okunur kabul edin.

## Ref adlandırma kuralları

| Desen | Anlamı |
|---------|---------|
| `refs/heads/<name>` | Yerel dal |
| `refs/tags/<name>` | Tag (hafif veya açıklamalı) |
| `refs/remotes/<remote>/<name>` | Uzak izleme dalı |
| `refs/stash` | Stash yığını |
| `refs/notes/<namespace>` | Git notları |
| `HEAD` | Geçerli ödeme (sembolik veya ayrık) |
| `FETCH_HEAD` | Son getirme sonucu (git tarafından yazılır; Pitmaster'in `fetch()` işlemi bunu yazmaz) |
| `MERGE_HEAD` | Birleştirilen dal (birleştirme sırasında) |
| `ORIG_HEAD` | Önceki HEAD (riskli işlemlerden önce) |

## Repository üzerinden ref'lerle çalışma

```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');
```