Посилання

Посилання (references) — це іменовані вказівники на коміти. Гілки, теги, HEAD і посилання для відстеження віддалених гілок — це посилання. Pitmaster читає посилання з окремих файлів, packed-refs і Reftable, а записує в окремі файли та packed-refs.

RefDatabase

RefDatabase — це комбінований шар, який спочатку шукає окремі посилання, потім у Reftable (якщо репозиторій його має), а далі в packed-refs.

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

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

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

Рядки, що починаються з ^, містять значення розіменування: коміт, на який зрештою вказує анотований тег.

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 може містити значення розіменування (розіменоване значення) у рядку після посилання на тег. Це значення — коміт, на який зрештою вказує об’єкт тегу (можливо, через кілька об’єктів тегів).

$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

Символічні посилання вказують на інші посилання, а не безпосередньо на об’єкти.

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>

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, тому такі репозиторії слід вважати доступними лише для читання.

Угоди щодо назв посилань

Робота з посиланнями через Repository

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