Alustamine

Paigaldamine

Installige Pitmaster käsuga Composer:

composer require pitmaster/pitmaster

Nõuded

• PHP 8.2+ koos kirjutuskaitstud klasside, enumite ja konstruktoris tehtava atribuutide määramisega
• ext-zlib objektide tihendamiseks ja lahtipakkimiseks (enamikus paigaldustes sisseehitatud)
• ext-json toiminguoleku failide ja Git LFS API koormiste jaoks
• ext-mbstring, deklareeritud failis composer.json, seega vajab Composer seda installimise ajal
• ext-ctype räsi valideerimiseks (enamikus PHP järgudes lubatud, kuid failis composer.json deklareerimata)

Põhihoidla toimingud ei vaja binaarfaili git, FFI-d ega väliseid abivahendeid. Valikulistel funktsioonidel on täiendavad käitusaja nõuded: hook’ide käivitamine kasutab proc_open(), transport SSH kasutab laadimise korral ext-ssh2-t ja muul juhul käivitab süsteemi binaarfaili ssh käsu proc_open() kaudu.

Olemasoleva hoidla avamine

use Pitmaster\Pitmaster;

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

See avab hoidla antud asukohas. Pitmaster leiab kataloogi .git (või lahendab seotud tööpuude korral faili .git) ning lähtestab objektide andmebaasi, viiteandmebaasi ja konfiguratsiooni.

open(), init() ja clone() aktsepteerivad viimase argumendina valikute massiivi:

// 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’id käivitatakse vaikimisi. Pitmaster::processFreeOptions() tagastab ['processes' => false, 'hooks' => false]; kohalik lugemine ja kirjutamine toimivad sellise käitleja korral edasi.

Kontrollimine, kas asukoht on hoidla

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

Uue hoidla lähtestamine

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

See loob kataloogistruktuuri .git, mis sisaldab objekte, viiteid, HEAD-i (osutab väärtusele refs/heads/main) ja vaikekonfiguratsiooni.

SHA-256 hoidla loomiseks andke teise argumendina objektivorming:

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

Selle hoidla objektitunnused koosnevad 64 kuueteistkümnendmärgist ja konfiguratsioonis on kirjas extensions.objectformat = sha256. Hiljem avatud hoidlad loevad vormingu konfiguratsioonikirjest.

HEAD-commit’i lugemine

$head = $repo->head();

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

Meetod head() lahendab HEAD-i (järgides sümboolseid viiteid) ja tagastab objekti Commit.

Harude ja siltide loetlemine

// 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']

Commit-ajaloo läbimine

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

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

Võite alustada ka kindlast commit’ist:

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

Tööpuidu oleku kontrollimine

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

Failide valikusse lisamine ja commit’i tegemine

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

Autori nimi ja e-posti aadress lahendatakse järgmises järjekorras: keskkonnamuutujad PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, keskkonnamuutujad GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL, konstandid PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, hoidla enda .git/config (user.name ja user.email) ning viimaks Pitmaster <pitmaster@localhost>. Loetakse ainult hoidla konfiguratsioonifaili (ja faile, mida see kaasab), mitte ~/.gitconfig. Commit’i tegija lahendatakse samamoodi nimede *_COMMITTER_* alusel ja vaikeväärtusena kasutatakse autori konstante.

Erinevuste arvutamine

// 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();

Kaughoidla kloonimine

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

See tuvastab viited, hangib pakifaili, seadistab kaugjälgitavad harud ja lülitab välja vaikimisi haru. HTTP(S) URL-id kasutavad nutikat HTTP-i ja lähevad vajaduse korral üle lihtsustatud HTTP-ile; SSH URL-id kasutavad SSH-transporti. Madala sügavusega kloonimiseks edastage sügavus kolmanda argumendina: Pitmaster::clone($url, $path, 1).

Loe suvalist objekti räsi järgi

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

Konfiguratsioon

Pitmaster järgib autoriandmete ja kaug-URL-ide puhul hoidla .git/config-i. Saate määrata ka globaalsed vaikeväärtused konstantidega PHP, mis tuleb määratleda enne Pitmaster käivitamist:

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

Baidiväärtus võib olla täisarv või string, mille lõpus on k, m või g ('256M'). Vigased väärtused asendatakse vaikeväärtusega.

Keskkonnamuutujad kirjutavad identiteedikonstandid üle: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, nende PITMASTER_COMMITTER_*-vasted ning giti enda muutujad GIT_AUTHOR_* ja GIT_COMMITTER_*. Transport SSH loeb muutujaid PITMASTER_SSH_*, mida kirjeldatakse jaotises Protokollid.

Räsialgoritmi jaoks konstanti pole. Objektivorming valitakse hoidla loomisel (Pitmaster::init($path, 'sha256') või init --object-format=sha256 väärtusega CLI) ja loetakse seejärel hoidla konfiguratsioonist.