# Препратки

Препратките са именувани указатели към комити. Клоновете, етикетите, HEAD и препратките за проследяване на отдалечени клонове са препратки. Pitmaster чете препратки от свободни файлове, packed-refs и reftable, а записва свободни файлове и packed-refs.

## RefDatabase

`RefDatabase` е съставният слой, който първо търси свободни препратки, после в reftable (ако хранилището има такъв), а след това в 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');
```

За свързани работни дървета `RefDatabase` съхранява HEAD и останалите псевдопрепратки за всяко работно дърво (`ORIG_HEAD`, `MERGE_HEAD`, `CHERRY_PICK_HEAD`, `REVERT_HEAD`, `REBASE_HEAD`, `BISECT_HEAD`) в git директорията на съответното работно дърво. Клоновете, етикетите и другите записи `refs/` се записват в общата директория, а `packed-refs` винаги се чете от нея.

## Свободни препратки

Свободните препратки са отделни файлове в `.git/refs/`. Всеки файл съдържа шестнадесетичния хеш на целевия обект (40 знака или 64 за SHA-256), последван от нов ред.

```
.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 е специална препратка, която може да бъде:

**Символна**: сочи към друга препратка (най-често, когато сте в клон):
```
ref: refs/heads/main\n
```

**Откачена**: сочи директно към хеша на комит:
```
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";
}
```

## Пакетирани препратки

Файлът `packed-refs` обединява много препратки в един файл за по-голяма ефективност. Git го създава по време на `git pack-refs` или `git gc`.

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

Редовете, започващи с `^`, са обелени стойности: комитът, към който в крайна сметка сочи анотиран етикет.

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

### Обелени стойности

За анотирани етикети файлът packed-refs може да включва обелена (разименувана) стойност на реда след препратката към етикета. Обелената стойност е комитът, към който в крайна сметка сочи обектът на етикета (възможно е това да става през няколко обекта на етикети).

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

## Ред на разрешаване на препратките

При разрешаване на препратка Pitmaster проверява в следния ред:

1. Свободна препратка (файл в `.git/refs/`)
2. Reftable, ако `.git/reftable/tables.list` съществува
3. Пакетирана препратка (запис в `.git/packed-refs`)

Свободните препратки имат приоритет. Когато пакетирана препратка се актуализира, новата стойност се записва като свободна препратка (файлът packed-refs не се пренаписва). При изтриване на препратка се премахват както свободният файл, така и пакетираният запис. `$repo->packRefs()` пренаписва `packed-refs` според текущите препратки и премахва свободните файлове.

## SymbolicRef

Символните препратки сочат към други препратки, а не директно към обекти.

```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 записва кога се променят препратките, което позволява на `git reflog` да показва историята на HEAD и върховете на клоновете.

Файловете Reflog се намират в `.git/logs/`:
```
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash
```

Всеки ред записва:
```
<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 използва reflog на `refs/stash` за съхранение на стека си.

## Reftable

Reftable е по-нов двоичен формат за съхранение на препратки, проектиран за по-добра производителност при много препратки (хиляди клонове). Той заменя както свободните препратки, така и packed-refs.

Файловете Reftable се съхраняват в `.git/reftable/` и съдържат:
- Записи за препратки (сортирани по име)
- Записи в лога (записи от reflog)
- Индексиране на ниво блок за бързи търсения

Pitmaster чете записите за препратки от файловете reftable, когато са налични; записите в лога не се четат. Когато има reftable, той заменя `packed-refs` при извеждане на списъка. Актуализациите на препратките винаги се записват като свободни файлове, които git не чете в хранилище с reftable, затова третирайте хранилищата с reftable като само за четене.

## Конвенции за именуване на препратки

| Шаблон | Значение |
|---------|---------|
| `refs/heads/<name>` | Локален клон |
| `refs/tags/<name>` | Етикет (лек или анотиран) |
| `refs/remotes/<remote>/<name>` | Клон за проследяване на отдалечено хранилище |
| `refs/stash` | Стек stash |
| `refs/notes/<namespace>` | Бележки Git |
| `HEAD` | Текущо извлечено състояние (символно или откачено) |
| `FETCH_HEAD` | Резултат от последното извличане (записва се от git; Pitmaster на `fetch()` не го записва) |
| `MERGE_HEAD` | Клонът, който се слива (при сливане) |
| `ORIG_HEAD` | Предишен HEAD (преди опасни операции) |

## Работа с препратки чрез 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');
```