Kirjoittaminen repositorioihin

Pitmaster kirjoittaa git-repositorioita käyttäen samoja binaarimuotoja kuin gitin kanoninen git-binaari. Objektit kirjoitetaan irto-objektivarastoon (zlib-pakattuina), indeksi kirjoitetaan v2-muodossa (tai v3-muodossa, jos merkinnät tarvitsevat laajennettuja lippuja; olemassa oleva indeksi säilyttää versionsa), ja viitteet kirjoitetaan irtotiedostoina. Kirjoitetut tiedot voi varmentaa komennolla git fsck --strict.

Repositorion alustaminen

use Pitmaster\Pitmaster;

$repo = Pitmaster::init('/path/to/new-project');

Tämä luo:

• .git/objects/ (tyhjä objektivarasto)
• .git/refs/heads/ ja .git/refs/tags/ (tyhjät viitehakemistot)
• .git/HEAD, joka sisältää ref: refs/heads/main
• .git/hooks/, .git/info/exclude ja .git/description
• .git/config oletusasetuksilla

Välitä 'sha256' toisena argumenttina luodaksesi SHA-256-repositorion: Pitmaster::init($path, 'sha256').

Oletusasetuksissa ei määritetä avainta core.logallrefupdates, joten Pitmaster ei kirjaa luomansa repositorion reflog-merkintöjä ennen kuin asetat avaimeksi true (#8). Komennolla git init luodut repositoriot määrittävät sen jo valmiiksi.

Tiedostojen lisääminen indeksiin

add

$repo->add('src/Feature.php');
$repo->add('src/Feature.php', 'tests/FeatureTest.php', 'README.md');

Kukin argumentti on tiedostopolku suhteessa työhakemiston juureen. Hakemistoja ja jokerimerkkejä ei laajenneta, ja puuttuva tiedosto aiheuttaa virheen RuntimeException. Kullekin tiedostolle Pitmaster:

1. Lukee tiedoston sisällön työhakemistosta
2. Luo Blob-objektin ja laskee sen tiivisteen
3. Kirjoittaa blobin sijaintiin .git/objects/ (zlib-pakattuna)
4. Päivittää kyseisen polun indeksimerkinnän uudella tiivisteellä ja tiedoston metatiedoilla

remove

$repo->remove('old-file.txt');
$repo->remove('-r', 'src');
$repo->remove('--cached', 'old-file.txt');

Poistaa seuratut polut indeksistä ja työhakemistosta. Käytä asetusta --cached vain indeksistä poistamiseen tai asetusta -r / --recursive seurattujen hakemistojen poistamiseen.

mv

$repo->mv('old-name.php', 'new-name.php');

Nimeää tiedoston uudelleen työhakemistossa, poistaa vanhan indeksimerkinnän ja lisää uuden.

Commitien luominen

$commitId = $repo->commit('Fix null pointer bug');
echo $commitId->hex;

Commit-prosessi:

1. Rakenna puu indeksistä: indeksimerkintöjen litteä luettelo järjestetään puuhierarkiaksi (hakemistoista tulee puuobjekteja, tiedostot ovat blob-viittauksia). Kukin puu kirjoitetaan objektivarastoon.
2. Määritä ylätaso: nykyisestä HEAD-commitista tulee ylätaso. Juuricommitilla (repositorion ensimmäisellä commitilla) ei ole ylätasoja.
3. Määritä tekijä: haetaan ympäristömuuttujista PITMASTER_AUTHOR_* ja GIT_AUTHOR_*, sitten vakioista PITMASTER_AUTHOR_NAME/PITMASTER_AUTHOR_EMAIL, sitten .git/config-asetuksesta (user.name/user.email) ja lopuksi asetuksesta Pitmaster <pitmaster@localhost>. Commitin tekijä selvitetään samalla tavalla.
4. Kirjoita commit-objekti: commitin sisältö (tree, parent, author, committer ja viesti) sarjoitetaan, tiivistetään ja kirjoitetaan.
5. Päivitä HEAD: haara, johon HEAD viittaa, päivitetään uuteen commit-tiivisteeseen.

Koukkuja suoritetaan näiden vaiheiden yhteydessä (pre-commit, prepare-commit-msg, commit-msg, post-commit), paitsi jos kahva on avattu asetuksella ['hooks' => false]. commit() aiheuttaa virheen, jos viesti puuttuu, puu ei ole muuttunut HEADiin verrattuna tai indeksissä on ratkaisemattomia polkuja.

Mukautettu tekijä

$author = 'Jane Smith <jane@example.com> 1700000000 +0000';
$commitId = $repo->commit('Add feature', $author);

Varmennus komennolla git fsck

Pitmaster-integraatiotestit tarkistavat kirjoitetut objektit komentoa git fsck --strict vasten, ja voit tehdä saman tarkistuksen itse:

cd /path/to/repo
git fsck --strict

Jos Pitmaster kirjoittaa virheellisen objektin, git fsck ilmoittaa virheestä heti.

Haarojen hallinta

Haaran luominen

// Branch from HEAD
$repo->createBranch('feature/new-thing');

// Branch from a specific commit
$repo->createBranch('hotfix', $repo->resolve('v1.0.0'));

Luo viitetiedoston sijaintiin .git/refs/heads/<name>; tiedosto sisältää kohdecommitin tiivisteen.

Haaran poistaminen

$repo->deleteBranch('feature/old');

Haaran vaihtaminen

$repo->checkout('feature/login');

Päivittää HEADin haaraan osoittavaksi symboliseksi viitteeksi, palauttaa indeksin vastaamaan haaran kärjen puuta ja päivittää työhakemiston.

Poluissa, joiden sisältö eroaa puiden välillä, olevat paikalliset muutokset keskeyttävät checkoutin virheellä RuntimeException. Kaikkien muiden seurattujen tiedostojen commitoimattomat muutokset korvataan haaran sisällöllä, jos git säilyttäisi ne (#2). Commitoi tai kätke muutokset ennen haaran vaihtamista.

Yhdistämisen tarkistaminen

if ($repo->isBranchMerged('feature/done')) {
    $repo->deleteBranch('feature/done');
}

Tagien hallinta

Kevyt tagi

$repo->createLightweightTag('v1.0.0');                          // At HEAD
$repo->createLightweightTag('v0.9.0', $repo->resolve('HEAD~5'));

Kevyt tagi on pelkkä viite, joka osoittaa suoraan committiin.

Annotated-tagi

$tagId = $repo->createTag('v2.0.0', 'Release version 2.0.0');

Annotated-tagi luo tagiobjektin (joka sisältää tagin luojan, viestin ja kohteen) sekä siihen osoittavan viitteen. Tagin luoja on nykyinen commitin tekijä, joka selvitetään samalla tavalla kuin commitin tekijä.

Mukautettu tagin luoja

$tagId = $repo->createTag(
    'v2.0.0',
    'Release version 2.0.0',
    $repo->resolve('HEAD'),
    'Jane Smith <jane@example.com> 1700000000 +0000',
);

Viitteiden suora päivittäminen

$repo->updateRef('refs/heads/main', $commitId);
$repo->updateRef('refs/tags/latest', $commitId);

Objektien suora kirjoittaminen

Edistyneissä käyttötapauksissa voit kirjoittaa objekteja käyttämättä korkean tason API-rajapintaa.

Blobin kirjoittaminen

use Pitmaster\Object\Blob;

$blob = Blob::fromContent('Hello, world!');
$id = $repo->writeObject($blob);
echo $id->hex;  // SHA-1 of "blob 13\0Hello, world!"

Välitä Blob::fromContent('Hello, world!', 'sha256')-repositoriossa algoritmi: SHA-256.

Puun kirjoittaminen

use Pitmaster\Object\Tree;
use Pitmaster\Object\TreeEntry;
use Pitmaster\Object\ObjectId;

$entries = [
    new TreeEntry('100644', 'README.md', $blobId),
    new TreeEntry('40000', 'src', $subtreeId),
];

$tree = Tree::fromEntries($entries);
$id = $repo->writeObject($tree);

Tree::fromEntries() kirjoittaa merkinnät annetussa järjestyksessä ja tilamerkkijonot annettuina. Välitä ne gitin puujärjestyksessä (nimen mukaan; hakemistojen nimeen verrataan lisättynä loppuun /) ja anna hakemistojen tilaksi 40000: git tallentaa puutilat ilman alkunollaa, ja git fsck --strict hylkää 040000.

Commitin kirjoittaminen

use Pitmaster\Object\Commit;
use Pitmaster\Object\ObjectId;
use Pitmaster\Object\ObjectType;

$content = Commit::buildContent(
    tree: $treeId,
    parents: [$parentId],
    author: 'Name <email> 1700000000 +0000',
    committer: 'Name <email> 1700000000 +0000',
    message: "Commit message\n",
);

$commitId = ObjectId::compute(ObjectType::Commit, $content);
$commit = Commit::parse($content, $commitId);
$repo->writeObject($commit);

Resetointi

// Soft: move HEAD only
$repo->reset('HEAD~1', 'soft');

// Mixed: move HEAD + reset index (default)
$repo->reset('HEAD~1');

// Hard: move HEAD + reset index + reset working tree
$repo->reset('HEAD~3', 'hard');

Palauttaminen

// Restore a file from the index into the worktree
$repo->restore('src/File.php');

// Restore the index version from HEAD (the worktree is left alone)
$repo->restore('src/File.php', staged: true);

// Restore from a specific commit
$repo->restore('src/File.php', 'HEAD~1');

// Restore both index and worktree from a specific commit
$repo->restore('src/File.php', 'HEAD~1', staged: true, worktree: true);

Cherry-pick ja revert

// Apply a commit on the current branch
$newId = $repo->cherryPick('feature~1');

// Undo a commit
$revertId = $repo->revert('HEAD~2');

Molemmat hyväksyvät minkä tahansa revision, jonka resolve() hyväksyy. Täydet tiivisteet toimivat, lyhennetyt eivät.