# Hivatkozások

A hivatkozások (refs) elnevezett mutatók commitokra. Az ágak, a címkék, a HEAD és a távoli követő hivatkozások mind hivatkozások. Pitmaster laza fájlokból, packed-refs fájlból és reftable-ből olvas hivatkozásokat, és laza fájlokba, valamint packed-refs fájlba ír.

## RefDatabase

A `RefDatabase` az összetett réteg, amely először a laza hivatkozások között keres, majd a reftable-ben (ha van ilyen a tárolóban), végül a packed-refs fájlban.

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

Összekapcsolt munkafák esetén a `RefDatabase` a HEAD-et és a munkafánkénti többi pszeudo-hivatkozást (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) a munkafához tartozó git könyvtárban tartja. Az ágak, címkék és egyéb `refs/` bejegyzések a közös könyvtárba kerülnek, a `packed-refs` pedig mindig a közös könyvtárból olvasható.

## Laza hivatkozások

A laza hivatkozások egyedi fájlok az `.git/refs/` könyvtárban. Minden fájl a célobjektum hexadecimális hashét tartalmazza (40 karakter, illetve 64 az SHA-256 esetében), amelyet egy újsor követ.

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

A HEAD egy speciális hivatkozás, amely lehet:

**Szimbolikus**: egy másik hivatkozásra mutat (ez a leggyakoribb ág esetén):
```
ref: refs/heads/main\n
```

**Leválasztott**: közvetlenül egy commit hashére mutat:
```
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";
}
```

## Csomagolt hivatkozások

A `packed-refs` fájl a hatékonyság érdekében sok hivatkozást egyetlen fájlba egyesít. Az Git hozza létre `git pack-refs` vagy `git gc` során.

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

Az `^` karakterrel kezdődő sorok feloldott értékek: az a commit, amelyre egy megjegyzésekkel ellátott címke végső soron mutat.

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

### Feloldott értékek

A megjegyzésekkel ellátott címkék esetén a packed-refs fájl a címkehivatkozás utáni sorban tartalmazhatja a feloldott (dereferált) értéket. A feloldott érték az a commit, amelyre a címkeobjektum végső soron mutat, akár több címkeobjektumon keresztül.

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

## Hivatkozásfeloldási sorrend

Hivatkozás feloldásakor az Pitmaster a következő sorrendben ellenőrzi:

1. Laza hivatkozás (fájl az `.git/refs/` könyvtárban)
2. Reftable, ha létezik az `.git/reftable/tables.list`
3. Csomagolt hivatkozás (bejegyzés az `.git/packed-refs` fájlban)

A laza hivatkozások élveznek elsőbbséget. Csomagolt hivatkozás frissítésekor az új érték laza hivatkozásként kerül kiírásra (a packed-refs fájl nem íródik újra). Hivatkozás törlése eltávolítja a laza fájlt és a csomagolt bejegyzést is. Az `$repo->packRefs()` újraírja az `packed-refs` fájlt az aktuális hivatkozások alapján, és eltávolítja a laza fájlokat.

## SymbolicRef

A szimbolikus hivatkozások más hivatkozásokra mutatnak, nem közvetlenül objektumokra.

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

A reflog rögzíti, mikor változnak a hivatkozások, így az `git reflog` meg tudja jeleníteni a HEAD és az ágak végpontjainak előzményeit.

Az Reflog fájlok az `.git/logs/` könyvtárban találhatók:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

Minden sor a következőket rögzíti:
```
<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',
);
```

A stash a `refs/stash` reflogját használja veremtárolóként.

## Reftable

Az Reftable egy újabb bináris formátum a hivatkozások tárolására, amelyet a sok (több ezer) ágat tartalmazó tárolók jobb teljesítményére terveztek. A laza hivatkozásokat és a packed-refs fájlt egyaránt kiváltja.

Az Reftable fájlok tárolási helye: `.git/reftable/`. Tartalmuk:
- Hivatkozásrekordok (név szerint rendezve)
- Naplórekordok (reflog-bejegyzések)
- Blokkszintű indexelés a gyors kereséshez

Az Pitmaster beolvassa a reftable-fájlok hivatkozásrekordjait, ha vannak ilyenek; a naplórekordokat nem olvassa be. Ha létezik reftable, az váltja fel az `packed-refs` fájlt a listázáskor. A hivatkozások frissítései mindig laza fájlokba íródnak, amelyeket a git nem olvas be reftable-t használó tárolóban, ezért a reftable-tárolókat csak olvashatóként kezelje.

## Hivatkozásnév-konvenciók

| Minta | Jelentés |
|---------|---------|
| `refs/heads/<name>` | Helyi ág |
| `refs/tags/<name>` | Címke (könnyű vagy megjegyzésekkel ellátott) |
| `refs/remotes/<remote>/<name>` | Távoli követő ág |
| `refs/stash` | Stash-verem |
| `refs/notes/<namespace>` | Git-jegyzetek |
| `HEAD` | Aktuális checkout (szimbolikus vagy leválasztott) |
| `FETCH_HEAD` | Utolsó lekérés eredménye (a git írja; az Pitmaster `fetch()` nem írja ezt) |
| `MERGE_HEAD` | Összevonás alatt álló ág (összevonás közben) |
| `ORIG_HEAD` | Előző HEAD (veszélyes műveletek előtt) |

## Hivatkozások kezelése a Repository segítségével

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