Atsauces

Atsauces ir nosaukti rādītāji uz commit objektiem. Atzari, tagi, HEAD un attālināto repozitoriju izsekošanas atsauces ir atsauces. Pitmaster nolasa atsauces no atsevišķiem failiem, packed-refs un reftable, kā arī raksta atsevišķus failus un packed-refs.

RefDatabase

RefDatabase ir saliktais slānis, kas vispirms meklē atsevišķās atsauces, pēc tam reftable (ja repozitorijā tāda ir) un tad 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');

Saistītām darba kokām RefDatabase glabā HEAD un citas katrai darba kokai paredzētās pseidoatsauces (ORIG_HEAD, MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, REBASE_HEAD, BISECT_HEAD) katras darba kokas git direktorijā. Atzari, tagi un citi refs/ ieraksti tiek rakstīti koplietojamajā direktorijā, un packed-refs vienmēr tiek nolasīts no koplietojamās direktorijas.

Atsevišķās atsauces

Atsevišķās atsauces ir atsevišķi faili vietā .git/refs/. Katrā failā ir mērķa objekta heksadecimālā jaucējvērtība (40 rakstzīmes vai 64 priekš SHA-256), kam seko jauna rinda.

.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 ir īpaša atsauce, kas var būt:

Simboliska: norāda uz citu atsauci (visbiežāk, ja esat uz atzara):

ref: refs/heads/main\n

Atvienota: norāda tieši uz commit jaucējvērtību:

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

Sapakotās atsauces

Fails packed-refs apvieno daudzas atsauces vienā failā, lai uzlabotu efektivitāti. Git to izveido, izpildot git pack-refs vai git gc.

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

Rindas, kas sākas ar ^, ir nolobītas vērtības: commit objekts, uz kuru galu galā norāda anotēts tags.

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

Nolobītās vērtības

Anotētiem tagiem packed-refs failā var būt nolobītā (dereferencētā) vērtība rindā pēc taga atsauces. Nolobītā vērtība ir commit objekts, uz kuru taga objekts galu galā norāda (iespējams, caur vairākiem tagu objektiem).

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

Atsauču atrisināšanas secība

Atrisinot atsauci, Pitmaster pārbauda šādā secībā:

1. Atsevišķā atsauce (fails vietā .git/refs/)
2. Reftable, ja pastāv .git/reftable/tables.list
3. Sapakota atsauce (ieraksts vietā .git/packed-refs)

Atsevišķām atsaucēm ir priekšroka. Atjauninot sapakotu atsauci, jaunā vērtība tiek ierakstīta kā atsevišķa atsauce (packed-refs fails netiek pārrakstīts). Dzēšot atsauci, tiek noņemts gan atsevišķais fails, gan sapakotais ieraksts. $repo->packRefs() pārraksta packed-refs, ņemot pašreizējās atsauces, un noņem atsevišķos failus.

SymbolicRef

Simboliskās atsauces norāda uz citām atsaucēm, nevis tieši uz objektiem.

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 reģistrē atsauču izmaiņu brīžus, ļaujot git reflog parādīt HEAD un atzaru galapunktu vēsturi.

Reflog faili atrodas vietā .git/logs/:

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

Katrā rindā ir reģistrēts:

<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 izmanto refs/stash reflog kā steka krātuvi.

Reftable

Reftable ir jaunāks binārais formāts atsauču glabāšanai, kas paredzēts labākai veiktspējai, ja atsauču ir daudz (tūkstošiem atzaru). Tas aizstāj gan atsevišķās atsauces, gan packed-refs.

Reftable faili tiek glabāti vietā .git/reftable/ un satur:

• Atsauču ierakstus (sakārtotus pēc nosaukuma)
• Žurnāla ierakstus (reflog ierakstus)
• Bloku līmeņa indeksēšanu ātrai uzmeklēšanai

Ja ir reftable faili, Pitmaster nolasa to atsauču ierakstus; žurnāla ieraksti netiek lasīti. Ja pastāv reftable, tas aizstāj packed-refs uzskaitīšanas vajadzībām. Atsauču atjauninājumi vienmēr tiek rakstīti kā atsevišķi faili, kurus git reftable repozitorijā nelasa, tāpēc uzskatiet reftable repozitorijus par tikai lasāmiem.

Atsauču nosaukumu veidošanas noteikumi

Darbs ar atsaucēm, izmantojot 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');