Pereiti prie turinio

Nuorodos

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: bfe242f

Nuorodos (refs) – tai pavadinti rodyklės į commit. Šakos, žymos, HEAD ir nuotolinio stebėjimo nuorodos yra refs. Pitmaster skaito refs iš laisvųjų failų, packed-refs ir reftable, o rašo į laisvuosius failus bei packed-refs.

RefDatabase

RefDatabase yra sudėtinis sluoksnis, kuris pirmiausia ieško laisvųjų refs, tada reftable (jei saugykla jį turi), o galiausiai 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');

Susietiems darbiniams medžiams RefDatabase perkelia HEAD ir kitas kiekvienam darbiniam medžiui skirtas pseudo-nuorodas (ORIG_HEAD, MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD, REBASE_HEAD, BISECT_HEAD) į atitinkamo darbinio medžio git katalogą. Šakos, žymos ir kiti refs/ įrašai rašomi į bendrą katalogą, o packed-refs visada skaitoma iš bendro katalogo.

Laisvosios nuorodos

Laisvosios nuorodos yra atskiri failai kataloge .git/refs/. Kiekviename faile yra tikslinio objekto šešioliktainė maiša (40 simbolių arba 64, kai naudojama SHA-256), po jos eina naujos eilutės simbolis.

Kodas
.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 yra speciali nuoroda, kuri gali būti:

Simbolinė: nurodo kitą nuorodą (dažniausiai, kai esate šakoje):

Kodas
ref: refs/heads/main\n

Atsieta: nurodo tiesiai į commit maišą:

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

Supakuotos nuorodos

Failas packed-refs sujungia daug nuorodų į vieną failą, kad būtų efektyviau. Git jį sukuria vykdant git pack-refs arba git gc.

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

Eilutės, prasidedančios ^, yra išskleistos reikšmės: commit, į kurį galiausiai nurodo anotuota žyma.

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

Išskleistos reikšmės

Anotuotų žymų atveju packed-refs faile po žymos nuorodos gali būti išskleista (nukreipta) reikšmė. Tai yra commit, į kurį galiausiai nurodo žymos objektas (galbūt per kelis žymos objektus).

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

Nuorodų sprendimo tvarka

Spręsdama nuorodą, Pitmaster tikrina tokia tvarka:

  1. Laisvoji nuoroda (failas kataloge .git/refs/)
  2. Reftable, jei egzistuoja .git/reftable/tables.list
  3. Supakuota nuoroda (įrašas faile .git/packed-refs)

Pirmenybė teikiama laisvosioms nuorodoms. Atnaujinus supakuotą nuorodą, nauja reikšmė įrašoma kaip laisvoji nuoroda (packed-refs failas neperrašomas). Ištrynus nuorodą pašalinamas ir laisvasis failas, ir supakuotas įrašas. $repo->packRefs() iš naujausių nuorodų perrašo packed-refs ir pašalina laisvuosius failus.

SymbolicRef

Simbolinės nuorodos nurodo į kitas nuorodas, o ne tiesiogiai į objektus.

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 įrašo nuorodų pakeitimus, todėl git reflog gali rodyti HEAD ir šakų viršūnių istoriją.

Reflog failai yra kataloge .git/logs/:

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

Kiekvienoje eilutėje įrašoma:

Kodas
<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',
);

Atidėtų pakeitimų stekas saugomas refs/stash reflog.

Reftable

Reftable yra naujesnis dvejetainis refs saugojimo formatas, sukurtas didesniam našumui, kai refs yra daug (tūkstančiai šakų). Jis pakeičia ir laisvąsias nuorodas, ir packed-refs.

Reftable failai saugomi .git/reftable/ ir juose yra:

  • Nuorodų įrašai (surikiuoti pagal pavadinimą)
  • Žurnalo įrašai (reflog įrašai)
  • Blokų lygmens indeksavimas greitai paieškai

Pitmaster skaito reftable failų nuorodų įrašus, jei tokių yra; žurnalo įrašai neskaitomi. Jei yra reftable, jis pakeičia packed-refs sąrašų sudarymui. Nuorodų naujiniai visada įrašomi į laisvuosius failus, kurių git neskaito reftable saugykloje, todėl reftable saugyklas laikykite tik skaitomomis.

Nuorodų pavadinimų taisyklės

Šablonas Reikšmė
refs/heads/<name> Vietinė šaka
refs/tags/<name> Žyma (lengvoji arba anotuota)
refs/remotes/<remote>/<name> Nuotolinė stebima šaka
refs/stash Atidėtų pakeitimų stekas
refs/notes/<namespace> Git pastabos
HEAD Dabartinė išsiregistruota versija (simbolinė arba atskirta)
FETCH_HEAD Paskutinio gavimo rezultatas (įrašo git; Pitmaster fetch() jo neįrašo)
MERGE_HEAD Sujungiama šaka (sujungimo metu)
ORIG_HEAD Ankstesnis HEAD (prieš pavojingas operacijas)

Darbas su refs per 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');