# Refs

Refs (referências) são ponteiros nomeados para commits. Branches, tags, HEAD e refs de rastreamento remoto são todos refs. Pitmaster lê refs de arquivos soltos, packed-refs e reftable, e grava arquivos soltos e packed-refs.

## RefDatabase

O `RefDatabase` é a camada composta que pesquisa primeiro as refs soltas, depois o reftable (quando o repositório tem um) e, por fim, o 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');
```

Em worktrees vinculadas, o `RefDatabase` mantém HEAD e as outras pseudo-refs por worktree (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) no diretório git por worktree. Branches, tags e outras entradas `refs/` são gravadas no diretório comum, e `packed-refs` é sempre lido do diretório comum.

## Refs soltas

Refs soltas são arquivos individuais em `.git/refs/`. Cada arquivo contém o hash hexadecimal do objeto de destino (40 caracteres, ou 64 para SHA-256), seguido de uma quebra de linha.

```
.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 é uma ref especial que pode ser:

**Simbólica**: aponta para outra ref (o mais comum, quando se está em uma branch):
```
ref: refs/heads/main\n
```

**Desanexada**: aponta diretamente para um hash de 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";
}
```

## Refs empacotadas

O arquivo `packed-refs` combina muitas refs em um único arquivo para maior eficiência. Git o cria durante `git pack-refs` ou `git gc`.

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

Linhas que começam com `^` são valores desreferenciados: o commit para o qual uma tag anotada aponta em última instância.

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

### Valores desreferenciados

Para tags anotadas, o arquivo packed-refs pode incluir o valor desreferenciado (resolvido) na linha após a ref da tag. O valor desreferenciado é o commit para o qual o objeto da tag aponta em última instância (possivelmente passando por vários objetos de tag).

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

## Ordem de resolução de refs

Ao resolver uma ref, Pitmaster verifica nesta ordem:

1. Ref solta (arquivo em `.git/refs/`)
2. Reftable, quando `.git/reftable/tables.list` existe
3. Ref empacotada (entrada em `.git/packed-refs`)

Refs soltas têm prioridade. Quando uma ref empacotada é atualizada, o novo valor é gravado como ref solta (o arquivo packed-refs não é regravado). Excluir uma ref remove tanto o arquivo solto quanto a entrada empacotada. `$repo->packRefs()` regrava `packed-refs` a partir das refs atuais e remove os arquivos soltos.

## SymbolicRef

Refs simbólicas são referências que apontam para outras referências, em vez de apontarem diretamente para objetos.

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

O reflog registra quando as refs mudam, permitindo que `git reflog` mostre o histórico de HEAD e das pontas das branches.

Os arquivos Reflog ficam em `.git/logs/`:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

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

O stash usa o reflog de `refs/stash` como armazenamento de pilha.

## Reftable

Reftable é um formato binário mais recente para armazenar refs, projetado para oferecer melhor desempenho com muitas refs (milhares de branches). Ele substitui tanto as refs soltas quanto packed-refs.

Os arquivos Reftable são armazenados em `.git/reftable/` e contêm:
- Registros de refs (ordenados por nome)
- Registros de log (entradas de reflog)
- Indexação em nível de bloco para pesquisas rápidas

Pitmaster lê os registros de refs dos arquivos reftable quando presentes; os registros de log não são lidos. Quando existe um reftable, ele substitui `packed-refs` para listagem. As atualizações de refs são sempre gravadas como arquivos soltos, que git não lê em um repositório com reftable; portanto, trate repositórios com reftable como somente leitura.

## Convenções de nomenclatura de refs

| Padrão | Significado |
|---------|---------|
| `refs/heads/<name>` | Branch local |
| `refs/tags/<name>` | Tag (leve ou anotada) |
| `refs/remotes/<remote>/<name>` | Branch de rastreamento remoto |
| `refs/stash` | Pilha de stash |
| `refs/notes/<namespace>` | Notas de Git |
| `HEAD` | Checkout atual (simbólico ou desanexado) |
| `FETCH_HEAD` | Resultado da última busca (gravado por git; o `fetch()` de Pitmaster não o grava) |
| `MERGE_HEAD` | Branch sendo mesclada (durante uma mesclagem) |
| `ORIG_HEAD` | HEAD anterior (antes de operações perigosas) |

## Trabalhando com refs por meio de 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');
```