# Refs

Refs (referencer) er navngivne pointere til commits. Branches, tags, HEAD og refs til fjernsporing er alle refs. Pitmaster læser refs fra løse filer, packed-refs og reftable og skriver til løse filer og packed-refs.

## RefDatabase

`RefDatabase` er det sammensatte lag, der først søger efter løse refs, derefter i reftable (hvis repositoryet har en) og til sidst i 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');
```

For sammenkædede worktrees gemmer `RefDatabase` HEAD og de andre pseudo-refs for hvert worktree (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) i git-mappen for det enkelte worktree. Branches, tags og andre poster i `refs/` skrives til den fælles mappe, og `packed-refs` læses altid fra den fælles mappe.

## Løse refs

Løse refs er individuelle filer i `.git/refs/`. Hver fil indeholder hex-hashen for målobjektet (40 tegn eller 64 for SHA-256), efterfulgt af et linjeskift.

```
.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 er en særlig ref, der kan være enten:

**Symbolsk**: peger på en anden ref (mest almindeligt, når du er på en branch):
```
ref: refs/heads/main\n
```

**Frakoblet**: peger direkte på en 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";
}
```

## Pakkede refs

Filen `packed-refs` samler mange refs i én fil for effektivitetens skyld. Git opretter den under `git pack-refs` eller `git gc`.

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

Linjer, der starter med `^`, er udfoldede værdier: den commit, som et annoteret tag i sidste ende peger på.

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

### Udfoldede værdier

For annoterede tags kan packed-refs-filen indeholde den udfoldede (derefererede) værdi på linjen efter tag-ref'en. Den udfoldede værdi er den commit, som tag-objektet i sidste ende peger på (eventuelt gennem flere tag-objekter).

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

## Rækkefølge ved opslag af refs

Når en ref slås op, kontrollerer Pitmaster i denne rækkefølge:

1. Løs ref (fil i `.git/refs/`)
2. Reftable, hvis `.git/reftable/tables.list` findes
3. Pakket ref (post i `.git/packed-refs`)

Løse refs har prioritet. Når en pakket ref opdateres, skrives den nye værdi som en løs ref (packed-refs-filen omskrives ikke). Når en ref slettes, fjernes både den løse fil og den pakkede post. `$repo->packRefs()` omskriver `packed-refs` ud fra de aktuelle refs og fjerner de løse filer.

## SymbolicRef

Symbolske refs er referencer, der peger på andre referencer i stedet for direkte på objekter.

```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 registrerer, hvornår refs ændres, så `git reflog` kan vise historikken for HEAD og branch-spidser.

Reflog-filer ligger i `.git/logs/`:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

Hver linje registrerer:
```
<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 bruger reflog for `refs/stash` som stack-lager.

## Reftable

Reftable er et nyere binært format til lagring af refs, designet til bedre ydeevne med mange refs (tusindvis af branches). Det erstatter både løse refs og packed-refs.

Reftable-filer gemmes i `.git/reftable/` og indeholder:
- Ref-poster (sorteret efter navn)
- Logposter (reflog-poster)
- Indeksering på blokniveau til hurtige opslag

Pitmaster læser ref-posterne fra reftable-filer, når de findes; logposter læses ikke. Når en reftable findes, erstatter den `packed-refs` ved visning af lister. Ref-opdateringer skrives altid som løse filer, som git ikke læser i et reftable-repository, så betragt reftable-repositories som skrivebeskyttede.

## Konventioner for navngivning af refs

| Mønster | Betydning |
|---------|---------|
| `refs/heads/<name>` | Lokal branch |
| `refs/tags/<name>` | Tag (letvægts eller annoteret) |
| `refs/remotes/<remote>/<name>` | Branch til fjernsporing |
| `refs/stash` | Stash-stack |
| `refs/notes/<namespace>` | Git-noter |
| `HEAD` | Aktuel checkout (symbolsk eller frakoblet) |
| `FETCH_HEAD` | Resultat af seneste fetch (skrevet af git; Pitmasters `fetch()` skriver det ikke) |
| `MERGE_HEAD` | Branch, der flettes ind (under merge) |
| `ORIG_HEAD` | Forrige HEAD (før risikable handlinger) |

## Arbejd med refs via 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');
```