# Referenzen

Referenzen (Refs) sind benannte Zeiger auf Commits. Branches, Tags, HEAD und Remote-Tracking-Refs sind allesamt Referenzen. Pitmaster liest Referenzen aus losen Dateien, packed-refs und reftable und schreibt lose Dateien sowie packed-refs.

## RefDatabase

Die `RefDatabase` ist die zusammengeführte Ebene, die zuerst lose Referenzen durchsucht, dann reftable (falls das Repository eine hat) und schließlich 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');
```

Bei verknüpften Arbeitsbäumen speichert `RefDatabase` HEAD und die anderen Pseudo-Refs pro Arbeitsbaum (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) im git-Verzeichnis des jeweiligen Arbeitsbaums. Branches, Tags und andere `refs/`-Einträge werden ins gemeinsame Verzeichnis geschrieben; `packed-refs` wird immer aus dem gemeinsamen Verzeichnis gelesen.

## Lose Referenzen

Lose Referenzen sind einzelne Dateien in `.git/refs/`. Jede Datei enthält den hexadezimalen Hash des Zielobjekts (40 Zeichen oder 64 bei SHA-256), gefolgt von einem Zeilenumbruch.

```
.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 ist eine spezielle Referenz, die entweder:

**Symbolisch** ist: Sie verweist auf eine andere Referenz (meistens, wenn du auf einem Branch bist):
```
ref: refs/heads/main\n
```

**Detached** ist: Sie verweist direkt auf einen Commit-Hash:
```
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";
}
```

## Gepackte Referenzen

Die Datei `packed-refs` fasst viele Referenzen in einer einzigen Datei zusammen, um Speicherplatz zu sparen. Git erstellt sie während `git pack-refs` oder `git gc`.

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

Mit `^` beginnende Zeilen sind aufgelöste Werte: der Commit, auf den ein annotiertes Tag letztlich verweist.

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

### Aufgelöste Werte

Bei annotierten Tags kann die packed-refs-Datei den aufgelösten (dereferenzierten) Wert in der Zeile nach der Tag-Referenz enthalten. Dieser Wert ist der Commit, auf den das Tag-Objekt letztlich verweist, möglicherweise über mehrere Tag-Objekte hinweg.

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

## Reihenfolge der Referenzauflösung

Beim Auflösen einer Referenz prüft Pitmaster in dieser Reihenfolge:

1. Lose Referenz (Datei in `.git/refs/`)
2. Reftable, falls `.git/reftable/tables.list` vorhanden ist
3. Gepackte Referenz (Eintrag in `.git/packed-refs`)

Lose Referenzen haben Vorrang. Wird eine gepackte Referenz aktualisiert, wird der neue Wert als lose Referenz gespeichert (die packed-refs-Datei wird nicht neu geschrieben). Beim Löschen einer Referenz werden sowohl die lose Datei als auch der gepackte Eintrag entfernt. `$repo->packRefs()` schreibt `packed-refs` aus den aktuellen Referenzen neu und entfernt die losen Dateien.

## SymbolicRef

Symbolische Referenzen verweisen auf andere Referenzen statt direkt auf Objekte.

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

Das Reflog protokolliert Änderungen an Referenzen. So kann `git reflog` die Historie von HEAD und Branch-Spitzen anzeigen.

Reflog-Dateien befinden sich in `.git/logs/`:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

Jede Zeile protokolliert:
```
<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',
);
```

Der Stash verwendet das Reflog von `refs/stash` als Stack-Speicher.

## Reftable

Reftable ist ein neueres Binärformat zum Speichern von Referenzen, das auf bessere Leistung bei vielen Referenzen (Tausenden Branches) ausgelegt ist. Es ersetzt sowohl lose Referenzen als auch packed-refs.

Reftable-Dateien werden in `.git/reftable/` gespeichert und enthalten:
- Referenzeinträge (nach Namen sortiert)
- Log-Einträge (Reflog-Einträge)
- Indizierung auf Blockebene für schnelle Suchvorgänge

Pitmaster liest die Referenzeinträge aus vorhandenen Reftable-Dateien, nicht jedoch die Log-Einträge. Wenn eine Reftable vorhanden ist, ersetzt sie `packed-refs` beim Auflisten. Aktualisierungen von Referenzen werden immer als lose Dateien geschrieben, die git in einem Reftable-Repository nicht liest. Behandle Reftable-Repositorys daher als schreibgeschützt.

## Konventionen für Referenznamen

| Muster | Bedeutung |
|---------|---------|
| `refs/heads/<name>` | Lokaler Branch |
| `refs/tags/<name>` | Tag (leichtgewichtig oder annotiert) |
| `refs/remotes/<remote>/<name>` | Remote-Tracking-Branch |
| `refs/stash` | Stash-Stack |
| `refs/notes/<namespace>` | Git-Notizen |
| `HEAD` | Aktueller Checkout (symbolisch oder detached) |
| `FETCH_HEAD` | Ergebnis des letzten Fetch (von git geschrieben; Pitmasters `fetch()` schreibt es nicht) |
| `MERGE_HEAD` | Branch, der gerade zusammengeführt wird (während eines Merge-Vorgangs) |
| `ORIG_HEAD` | Vorheriger HEAD (vor riskanten Operationen) |

## Mit Referenzen über Repository arbeiten

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