# Viitteet

Viitteet ovat nimettyjä osoittimia commit-objekteihin. Haarat, tagit, HEAD ja etähaaroja seuraavat viitteet ovat kaikki viitteitä. Pitmaster lukee viitteitä irrallisista tiedostoista, packed-refs-tiedostosta ja reftable-tiedostosta sekä kirjoittaa irrallisia tiedostoja ja packed-refs-tiedoston.

## RefDatabase

`RefDatabase` on yhdistelmäkerros, joka etsii ensin irrallisia viitteitä, sitten reftable-tiedostosta (jos tietovarastossa on sellainen) ja lopuksi packed-refs-tiedostosta.

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

Linkitetyissä työpuissa `RefDatabase` säilyttää HEADin ja muut työpuukohtaiset pseudoviitteet (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) työpuun omassa git-hakemistossa. Haarat, tagit ja muut `refs/`-merkinnät kirjoitetaan yhteiseen hakemistoon, ja `packed-refs` luetaan aina yhteisestä hakemistosta.

## Irralliset viitteet

Irralliset viitteet ovat yksittäisiä tiedostoja hakemistossa `.git/refs/`. Jokainen tiedosto sisältää kohdeobjektin heksadesimaalisen tiivisteen (40 merkkiä tai SHA-256-muodossa 64 merkkiä), jota seuraa rivinvaihto.

```
.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 on erityinen viite, joka voi olla joko:

**Symbolinen**: osoittaa toiseen viitteeseen (yleisintä haarassa ollessa):
```
ref: refs/heads/main\n
```

**Irrotettu**: osoittaa suoraan commit-tiivisteeseen:
```
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";
}
```

## Pakatut viitteet

`packed-refs`-tiedosto yhdistää useita viitteitä yhdeksi tiedostoksi tehokkuuden vuoksi. Git luo sen toiminnon `git pack-refs` tai `git gc` aikana.

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

Merkin `^` alussa olevat rivit ovat purettuja arvoja: commit, johon annotoitu tag lopulta osoittaa.

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

### Puretut arvot

Annotoitujen tagien kohdalla packed-refs-tiedosto voi sisältää puretun (viittauksen kohteen selvitetyn) arvon tagiviitteen jälkeisellä rivillä. Purettu arvo on commit, johon tagiobjekti lopulta osoittaa mahdollisesti usean tagiobjektin kautta.

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

## Viitteen ratkaisujärjestys

Kun viitettä ratkaistaan, Pitmaster tarkistaa seuraavassa järjestyksessä:

1. Irrallinen viite (tiedosto hakemistossa `.git/refs/`)
2. Reftable, kun `.git/reftable/tables.list` on olemassa
3. Pakattu viite (merkintä tiedostossa `.git/packed-refs`)

Irralliset viitteet ovat etusijalla. Kun pakattu viite päivitetään, uusi arvo kirjoitetaan irrallisena viitteenä (packed-refs-tiedostoa ei kirjoiteta uudelleen). Viitteen poistaminen poistaa sekä irrallisen tiedoston että pakatun merkinnän. `$repo->packRefs()` kirjoittaa `packed-refs` uudelleen nykyisten viitteiden perusteella ja poistaa irralliset tiedostot.

## SymbolicRef

Symboliset viitteet osoittavat toisiin viitteisiin suoraan objektien sijaan.

```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 tallentaa viitteiden muutokset, minkä ansiosta `git reflog` voi näyttää HEADin ja haarojen kärkien historian.

Reflog-tiedostot sijaitsevat hakemistossa `.git/logs/`:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

Kukin rivi tallentaa:
```
<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 käyttää pinotallennukseen viitteen `refs/stash` reflogia.

## Reftable

Reftable on uudempi binäärimuoto viitteiden tallentamiseen. Se on suunniteltu parantamaan suorituskykyä, kun viitteitä on paljon (tuhansia haaroja), ja korvaa sekä irralliset viitteet että packed-refs-tiedoston.

Reftable-tiedostot tallennetaan hakemistoon `.git/reftable/` ja ne sisältävät:
- Viitemerkinnät (lajiteltu nimen mukaan)
- Lokimerkinnät (reflog-merkinnät)
- Lohkotason indeksoinnin nopeita hakuja varten

Pitmaster lukee reftable-tiedostojen viitemerkinnät, jos niitä on; lokimerkintöjä ei lueta. Kun reftable on käytössä, se korvaa `packed-refs`-tiedoston luetteloitaessa. Viitteiden päivitykset kirjoitetaan aina irrallisina tiedostoina, joita git ei lue reftable-tietovarastossa, joten käsittele reftable-tietovarastoja vain luku -tilassa.

## Viitteiden nimeämiskäytännöt

| Kuvio | Merkitys |
|---------|---------|
| `refs/heads/<name>` | Paikallinen haara |
| `refs/tags/<name>` | Tagi (kevyt tai annotoitu) |
| `refs/remotes/<remote>/<name>` | Etähaaraa seuraava haara |
| `refs/stash` | Stash-pino |
| `refs/notes/<namespace>` | Git-muistiinpanot |
| `HEAD` | Nykyinen uloskirjaus (symbolinen tai irrotettu) |
| `FETCH_HEAD` | Viimeisin haun tulos (gitin kirjoittama; Pitmastern `fetch()` ei kirjoita sitä) |
| `MERGE_HEAD` | Yhdistettävä haara (yhdistämisen aikana) |
| `ORIG_HEAD` | Aiempi HEAD (ennen riskialttiita toimintoja) |

## Viitteiden käsittely Repositoryn kautta

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