Kezdő lépések

Telepítés

Telepítse az Pitmaster csomagot a(z) Composer használatával:

composer require pitmaster/pitmaster

Követelmények

• PHP 8.2+ readonly osztályokkal, enumokkal és konstruktorparaméterek előléptetésével
• ext-zlib objektumok tömörítéséhez és kicsomagolásához (a legtöbb telepítésben beépített)
• ext-json műveleti állapotfájlokhoz és Git LFS API adatokhoz
• ext-mbstring, az composer.json csomagban deklarálva, ezért az Composer telepítéskor megköveteli
• ext-ctype hash-ellenőrzéshez (a legtöbb PHP buildben engedélyezve, de az composer.json csomagban nincs deklarálva)

Az alapvető tárolóműveletekhez nincs szükség a git binárisra, FFI-re vagy külső segédprogramokra. Az opcionális funkciók további futásidejű követelményekkel járnak: a hookok végrehajtása a proc_open() használatával történik, a SSH átvitel pedig a ext-ssh2-t használja, ha az be van töltve; egyébként a rendszer ssh binárisát indítja el a proc_open() segítségével.

Meglévő tároló megnyitása

use Pitmaster\Pitmaster;

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

Ez megnyitja a megadott útvonalon található tárolót. Az Pitmaster megkeresi az .git könyvtárat (vagy összekapcsolt munkafák esetén felold egy .git fájlt), majd inicializálja az objektum-adatbázist, a hivatkozás-adatbázist és a konfigurációt.

Az open(), az init() és az clone() utolsó argumentumként beállításokat tartalmazó tömböt fogad el:

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

A hookok alapértelmezés szerint lefutnak. Az Pitmaster::processFreeOptions() ['processes' => false, 'hooks' => false] értéket ad vissza; az ilyen kezelővel a helyi olvasások és írások továbbra is működnek.

Útvonalról eldönteni, hogy tároló-e

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

Új tároló inicializálása

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

Ez létrehozza az .git könyvtárszerkezetét az objektumokkal, hivatkozásokkal, HEAD-del (amely az refs/heads/main értékre mutat) és az alapértelmezett konfigurációval.

SHA-256 tároló létrehozásához második argumentumként adja meg az objektumformátumot:

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

Az ilyen tárolóban az objektumazonosítók 64 hexadecimális karakterből állnak, a konfiguráció pedig rögzíti az extensions.objectformat = sha256 értéket. A később megnyitott tárolók a konfigurációs bejegyzésből veszik át a formátumot.

A HEAD commit beolvasása

$head = $repo->head();

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

Az head() metódus feloldja a HEAD-et (követve a szimbolikus hivatkozásokat), és egy Commit objektumot ad vissza.

Ágak és címkék listázása

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

Commitelőzmények bejárása

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

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

Kiindulhat egy adott commitból is:

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

Munkafa állapotának ellenőrzése

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

Fájlok előkészítése és commit létrehozása

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

A szerző nevét és e-mail-címét a rendszer a következő sorrendben oldja fel: az PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL környezeti változók, a GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL környezeti változók, az PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL konstansok, a tároló saját .git/config beállításai (user.name és user.email), végül pedig az Pitmaster <pitmaster@localhost>. A rendszer csak a tároló konfigurációs fájlját (és az általa bevont fájlokat) olvassa be, az ~/.gitconfig fájlt nem. A beküldő feloldása ugyanígy történik a *_COMMITTER_* nevek alapján, és hiányukban a szerzői konstansokra esik vissza.

Különbségek kiszámítása

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

Távoli tároló klónozása

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

Ez felderíti a hivatkozásokat, letölti a pack fájlt, beállítja a távoli követő ágakat, és kijelenti az alapértelmezett ágat. A HTTP(S) URL-ek intelligens HTTP protokollt használnak, és visszaváltanak a buta HTTP protokollra; a SSH URL-ek a SSH átvitelt használják. Sekély klónozáshoz harmadik argumentumként adja meg a mélységet: Pitmaster::clone($url, $path, 1).

Tetszőleges objektum beolvasása hash alapján

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

Konfiguráció

Az Pitmaster figyelembe veszi a tároló .git/config beállításait a szerzői adatokhoz és a távoli URL-ekhez. Globális alapértékeket is megadhat az PHP konstansokkal, az Pitmaster futása előtt:

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

A bájtérték megadható egész számként, vagy k, m, illetve g utótagot tartalmazó karakterláncként ('256M'). Érvénytelen érték esetén az alapérték lép életbe.

A környezeti változók felülírják az identitáskonstansokat: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, a PITMASTER_COMMITTER_* megfelelői, valamint a git saját GIT_AUTHOR_* és GIT_COMMITTER_* változói. A SSH átvitel az PITMASTER_SSH_* változókat olvassa be, amelyeket a Protokollok ismertet.

A hashalgoritmushoz nincs konstans. Az objektumformátumot a tároló létrehozásakor választja ki (Pitmaster::init($path, 'sha256') vagy init --object-format=sha256 az CLI esetében), majd később a tároló konfigurációjából olvassa be.