Darbo pradžia

Diegimas

Įdiekite Pitmaster naudodami Composer:

composer require pitmaster/pitmaster

Reikalavimai

• PHP 8.2+ su tik skaitomomis klasėmis, enum ir konstruktoriaus parametrų perkėlimu
• ext-zlib objektams suspausti ir išskleisti (daugumoje įdiegimų jau yra)
• ext-json operacijų būsenos failams ir Git LFS API duomenims
• ext-mbstring, nurodytas composer.json, todėl Composer jo reikalauja diegimo metu
• ext-ctype maišoms tikrinti (įjungtas daugumoje PHP versijų, bet nenurodytas composer.json)

Pagrindinėms saugyklos operacijoms nereikia git dvejetainio failo, FFI ar išorinių pagalbinių įrankių. Pasirinktinėms funkcijoms reikia papildomų vykdymo aplinkos galimybių: hook vykdymui naudojamas proc_open(), o SSH transportas naudoja ext-ssh2, jei jis įkeltas, o kitu atveju per proc_open() paleidžiamas sistemos ssh dvejetainis failas.

Atidaryti esamą saugyklą

use Pitmaster\Pitmaster;

$repo = Pitmaster::open('/path/to/project');

Taip atidaroma saugykla nurodytame kelyje. Pitmaster suranda .git katalogą (arba išsprendžia .git failą susietiems darbiniams medžiams) ir inicijuoja objektų duomenų bazę, nuorodų duomenų bazę bei konfigūraciją.

open(), init() ir clone() priima parinkčių masyvą kaip paskutinį argumentą:

// Do not run .git/hooks scripts for this handle
$repo = Pitmaster::open('/path/to/project', ['hooks' => false]);

// Do not start any process: no hooks, no fsmonitor hook, no clone/fetch/push, no SSH
$repo = Pitmaster::open('/path/to/project', Pitmaster::processFreeOptions());

Hook vykdomi pagal numatytuosius nustatymus. Pitmaster::processFreeOptions() grąžina ['processes' => false, 'hooks' => false]; vietinis skaitymas ir rašymas su tokia nuoroda veikia toliau.

Patikrinti, ar kelias yra saugykla

if (Pitmaster::isRepository('/path/to/project')) {
    $repo = Pitmaster::open('/path/to/project');
}

Inicijuoti naują saugyklą

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

Taip sukuriama .git katalogų struktūra su objektais, nuorodomis, HEAD (nurodančiu į refs/heads/main) ir numatytąja konfigūracija.

Norėdami sukurti SHA-256 saugyklą, kaip antrą argumentą perduokite objektų formatą:

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

Šios saugyklos objektų ID sudaro 64 šešioliktainiai simboliai, o konfigūracijoje įrašyta extensions.objectformat = sha256. Vėliau atidarytos saugyklos formatą nustato pagal šį konfigūracijos įrašą.

Nuskaityti HEAD įrašą

$head = $repo->head();

echo "Commit: {$head->id->hex}\n";
echo "Author: {$head->author}\n";
echo "Message: {$head->message}\n";

Metodas head() išsprendžia HEAD (sekdamas simbolines nuorodas) ir grąžina objektą Commit.

Išvardyti šakas ir žymas

// All branch names
$branches = $repo->branches();
// ['main', 'feature/login', 'bugfix/typo']

// Current branch name (null if detached)
$current = $repo->branch();
// 'main'

// All tag names
$tags = $repo->tags();
// ['v1.0.0', 'v1.1.0']

Pereiti įrašų istoriją

// Last 20 commits from HEAD
$commits = $repo->log(20);

foreach ($commits as $commit) {
    echo substr($commit->id->hex, 0, 7) . " {$commit->message}\n";
}

Taip pat galite pradėti nuo konkretaus įrašo:

$from = $repo->resolve('feature/login');
$commits = $repo->log(10, $from);

Patikrinti darbinio medžio būseną

use Pitmaster\Status\FileStatus;

$entries = $repo->status();

foreach ($entries as $entry) {
    if ($entry->index === FileStatus::Untracked) {
        echo "?? {$entry->path}\n";
    } elseif ($entry->index === FileStatus::Modified) {
        echo "M  {$entry->path}\n";
    } elseif ($entry->worktree === FileStatus::Modified) {
        echo " M {$entry->path}\n";
    }
}

Įtraukti failus į indeksą ir sukurti įrašą

// Stage specific files
$repo->add('src/Feature.php', 'tests/FeatureTest.php');

// Create a commit
$commitId = $repo->commit('Add new feature with tests');

echo "Created commit: {$commitId->hex}\n";

Autoriaus vardas ir el. paštas nustatomi tokia tvarka: PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL aplinkos kintamieji, GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL aplinkos kintamieji, konstantos PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, pačios saugyklos .git/config (user.name ir user.email) ir galiausiai Pitmaster <pitmaster@localhost>. Skaitomas tik saugyklos konfigūracijos failas (ir jo įtraukiami failai), o ~/.gitconfig neskaitomas. Įrašytojas nustatomas taip pat, naudojant *_COMMITTER_* pavadinimus; jei jų nėra, naudojamos autoriaus konstantos.

Apskaičiuoti skirtumus

// Unstaged changes (worktree vs index)
$diffs = $repo->diff();

foreach ($diffs as $diff) {
    echo $diff->format(); // Unified diff output
}

// Staged changes (index vs HEAD)
$staged = $repo->diffStaged();

Klonuoti nuotolinę saugyklą

$repo = Pitmaster::clone('https://github.com/user/repo.git', '/path/to/destination');

Aptinkamos nuorodos, gaunamas paketo failas, nustatomos nuotolinio sekimo šakos ir išimama numatytoji šaka. HTTP(S) URL naudoja išmanųjį HTTP ir, jam nepavykus, pereina prie paprastojo HTTP; SSH URL naudoja SSH transportą. Norėdami atlikti negilų klonavimą, kaip trečią argumentą perduokite gylį: Pitmaster::clone($url, $path, 1).

Nuskaityti bet kurį objektą pagal maišą

$object = $repo->readObject($fullHash); // full 40-character (or 64 for SHA-256) hex hash

if ($object instanceof \Pitmaster\Object\Blob) {
    echo $object->content;
} elseif ($object instanceof \Pitmaster\Object\Commit) {
    echo $object->message;
}

Konfigūracija

Pitmaster atsižvelgia į saugyklos .git/config, kurioje saugoma autoriaus informacija ir nuotoliniai URL. Taip pat galite nustatyti visuotines numatytąsias reikšmes naudodami PHP konstantas, apibrėžtas prieš paleidžiant Pitmaster:

define('PITMASTER_AUTHOR_NAME', 'Your Name');
define('PITMASTER_AUTHOR_EMAIL', 'you@example.com');
define('PITMASTER_HTTP_TIMEOUT', 60);        // Seconds
define('PITMASTER_MAX_DELTA_CHAIN', 50);     // Max delta chain depth
define('PITMASTER_OBJECT_CACHE_BYTES', '64M');

Baitų reikšmė gali būti sveikasis skaičius arba eilutė su priesaga k, m arba g ('256M'). Netinkamos reikšmės pakeičiamos numatytąja.

Aplinkos kintamieji turi pirmenybę prieš tapatybės konstantas: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, atitinkamos PITMASTER_COMMITTER_* reikšmės ir paties git kintamieji GIT_AUTHOR_* bei GIT_COMMITTER_*. SSH transportas nuskaito PITMASTER_SSH_* kintamuosius, aprašytus skiltyje Protokolai.

Maišos algoritmui nėra konstantos. Objektų formatas pasirenkamas kuriant saugyklą (Pitmaster::init($path, 'sha256') arba init --object-format=sha256 sistemoje CLI), o vėliau nuskaitomas iš saugyklos konfigūracijos.