# Riferimenti

I riferimenti (refs) sono puntatori denominati ai commit. Rami, tag, HEAD e riferimenti di tracciamento remoto sono tutti riferimenti. Pitmaster legge i riferimenti da file sciolti, packed-refs e reftable, e scrive file sciolti e packed-refs.

## RefDatabase

`RefDatabase` è il livello composito che cerca prima i riferimenti sciolti, poi reftable (se il repository ne contiene uno) e infine 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');
```

Per i worktree collegati, `RefDatabase` mantiene HEAD e gli altri pseudo-riferimenti specifici del worktree (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) nella directory git del singolo worktree. I rami, i tag e gli altri riferimenti `refs/` vengono scritti nella directory comune, e `packed-refs` viene sempre letto dalla directory comune.

## Riferimenti sciolti

I riferimenti sciolti sono file singoli in `.git/refs/`. Ogni file contiene l'hash esadecimale dell'oggetto di destinazione (40 caratteri, o 64 per SHA-256), seguito da un a capo.

```
.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 è un riferimento speciale che può essere:

**Simbolico**: punta a un altro riferimento (caso più comune, quando ci si trova su un ramo):
```
ref: refs/heads/main\n
```

**Distaccato**: punta direttamente all'hash di un commit:
```
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";
}
```

## Riferimenti impacchettati

Il file `packed-refs` combina molti riferimenti in un unico file per maggiore efficienza. Git lo crea durante `git pack-refs` o `git gc`.

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

Le righe che iniziano con `^` sono valori peeled: il commit a cui punta in ultima istanza un tag annotato.

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

### Valori peeled

Per i tag annotati, il file packed-refs può includere il valore peeled (dereferenziato) nella riga successiva a quella del riferimento al tag. Il valore peeled è il commit a cui punta in ultima istanza l'oggetto tag (anche passando per più oggetti tag).

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

## Ordine di risoluzione dei riferimenti

Quando risolve un riferimento, Pitmaster controlla in quest'ordine:

1. Riferimento sciolto (file in `.git/refs/`)
2. Reftable, se `.git/reftable/tables.list` esiste
3. Riferimento impacchettato (voce in `.git/packed-refs`)

I riferimenti sciolti hanno la precedenza. Quando si aggiorna un riferimento impacchettato, il nuovo valore viene scritto come riferimento sciolto (il file packed-refs non viene riscritto). L'eliminazione di un riferimento rimuove sia il file sciolto sia la voce impacchettata. `$repo->packRefs()` riscrive `packed-refs` usando i riferimenti correnti e rimuove i file sciolti.

## SymbolicRef

I riferimenti simbolici sono riferimenti che puntano ad altri riferimenti anziché direttamente agli oggetti.

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

Il reflog registra quando cambiano i riferimenti, consentendo a `git reflog` di mostrare la cronologia di HEAD e delle punte dei rami.

I file Reflog si trovano in `.git/logs/`:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

Ogni riga registra:
```
<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',
);
```

Lo stash usa il reflog di `refs/stash` come spazio di archiviazione dello stack.

## Reftable

Reftable è un formato binario più recente per archiviare i riferimenti, progettato per offrire prestazioni migliori con molti riferimenti (migliaia di rami). Sostituisce sia i riferimenti sciolti sia packed-refs.

I file Reftable sono archiviati in `.git/reftable/` e contengono:
- Record dei riferimenti (ordinati per nome)
- Record del log (voci del reflog)
- Indicizzazione a livello di blocco per ricerche rapide

Pitmaster legge i record dei riferimenti dai file reftable, se presenti; i record del log non vengono letti. Quando esiste un reftable, sostituisce `packed-refs` per l'elenco. Gli aggiornamenti dei riferimenti vengono sempre scritti come file sciolti, che git non legge in un repository reftable: pertanto, considerate i repository reftable come di sola lettura.

## Convenzioni per i nomi dei riferimenti

| Modello | Significato |
|---------|---------|
| `refs/heads/<name>` | Ramo locale |
| `refs/tags/<name>` | Tag (leggero o annotato) |
| `refs/remotes/<remote>/<name>` | Ramo di tracciamento remoto |
| `refs/stash` | Stack dello stash |
| `refs/notes/<namespace>` | Note di Git |
| `HEAD` | Checkout corrente (simbolico o distaccato) |
| `FETCH_HEAD` | Risultato dell'ultimo fetch (scritto da git; Pitmaster di `fetch()` non lo scrive) |
| `MERGE_HEAD` | Ramo in fase di merge (durante un merge) |
| `ORIG_HEAD` | HEAD precedente (prima di operazioni rischiose) |

## Uso dei riferimenti tramite 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');
```