Přejít k obsahu

Odkazy

Zobrazit jako Markdown Upravit na GitHub Dokumentace na bfe242f

Odkazy (reference) jsou pojmenované ukazatele na commity. Větve, štítky, HEAD i vzdálené sledovací odkazy jsou odkazy. Pitmaster čte odkazy z volných souborů, packed-refs a reftable a zapisuje do volných souborů a packed-refs.

RefDatabase

RefDatabase je složená vrstva, která nejprve hledá volné odkazy, poté reftable (pokud jej úložiště má) a nakonec 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');

U propojených pracovních stromů ukládá RefDatabase HEAD a další pseudo-odkazy specifické pro pracovní strom (ORIG_HEAD, MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, REBASE_HEAD, BISECT_HEAD) do adresáře git daného pracovního stromu. Větve, štítky a další položky refs/ se zapisují do společného adresáře a packed-refs se vždy čte ze společného adresáře.

Volné odkazy

Volné odkazy jsou samostatné soubory v .git/refs/. Každý soubor obsahuje hexadecimální hash cílového objektu (40 znaků, nebo 64 pro SHA-256) a za ním nový řádek.

Kód
.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 je zvláštní odkaz, který může být:

Symbolický: ukazuje na jiný odkaz (nejběžnější případ při práci ve větvi):

Kód
ref: refs/heads/main\n

Odpojený: ukazuje přímo na hash commitu:

Kód
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";
}

Zabalené odkazy

Soubor packed-refs slučuje mnoho odkazů do jednoho souboru pro vyšší efektivitu. Git jej vytváří během git pack-refs nebo git gc.

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

Řádky začínající na ^ jsou rozbalené hodnoty: commit, na který nakonec ukazuje anotovaný štítek.

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

Rozbalené hodnoty

U anotovaných štítků může soubor packed-refs obsahovat rozbalenou (dereferencovanou) hodnotu na řádku za odkazem na štítek. Rozbalená hodnota je commit, na který objekt štítku nakonec ukazuje, případně přes několik objektů štítků.

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

Pořadí vyhodnocování odkazů

Při vyhodnocování odkazu kontroluje Pitmaster následující pořadí:

  1. Volný odkaz (soubor v .git/refs/)
  2. Reftable, pokud existuje .git/reftable/tables.list
  3. Zabalený odkaz (položka v .git/packed-refs)

Volné odkazy mají přednost. Při aktualizaci zabaleného odkazu se nová hodnota zapíše jako volný odkaz (soubor packed-refs se nepřepisuje). Odstraněním odkazu se odstraní volný soubor i položka v packed-refs. $repo->packRefs() přepíše packed-refs podle aktuálních odkazů a odstraní volné soubory.

SymbolicRef

Symbolické odkazy jsou reference, které ukazují na jiné reference, nikoli přímo na objekty.

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 zaznamenává změny odkazů a umožňuje git reflog zobrazit historii HEAD a vrcholů větví.

Soubory Reflog se nacházejí v .git/logs/:

Kód
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash

Každý řádek zaznamenává:

Kód
<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 používá reflog refs/stash jako úložiště zásobníku.

Reftable

Reftable je novější binární formát pro ukládání odkazů, navržený pro vyšší výkon při velkém počtu odkazů (tisíce větví). Nahrazuje volné odkazy i packed-refs.

Soubory Reftable jsou uloženy v .git/reftable/ a obsahují:

  • Záznamy odkazů (seřazené podle názvu)
  • Záznamy protokolů (položky reflog)
  • Indexování na úrovni bloků pro rychlé vyhledávání

Pitmaster čte záznamy odkazů ze souborů reftable, jsou-li k dispozici; záznamy protokolů se nečtou. Pokud reftable existuje, nahrazuje packed-refs při výpisu. Aktualizace odkazů se vždy zapisují jako volné soubory, které git v úložišti reftable nečte, proto úložiště reftable považujte za úložiště pouze pro čtení.

Konvence pojmenování odkazů

Vzor Význam
refs/heads/<name> Místní větev
refs/tags/<name> Štítek (lehký nebo anotovaný)
refs/remotes/<remote>/<name> Vzdálená sledovací větev
refs/stash Zásobník stash
refs/notes/<namespace> Poznámky Git
HEAD Aktuální checkout (symbolický nebo odpojený)
FETCH_HEAD Výsledek posledního načtení (zapisuje git; Pitmaster fetch() jej nezapisuje)
MERGE_HEAD Větev slučovaná právě při merge
ORIG_HEAD Předchozí HEAD (před nebezpečnými operacemi)

Práce s odkazy přes 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');