Gå til indhold

Refs

Vis som Markdown Rediger på GitHub Dokumentation hos bfe242f

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.

Kode
.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 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):

Kode
ref: refs/heads/main\n

Frakoblet: peger direkte på en commit-hash:

Kode
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.

Kode
# 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/:

Kode
.git/logs/HEAD
.git/logs/refs/heads/main
.git/logs/refs/stash

Hver linje registrerer:

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