Začínáme

Zobrazit jako Markdown Upravit na GitHub Dokumentace na bfe242f

Instalace

Nainstalujte Pitmaster pomocí Composer:

Shell

composer require pitmaster/pitmaster

Požadavky

PHP 8.2+ s třídami readonly, výčtovými typy a propagací konstruktoru
ext-zlib pro kompresi a dekompresi objektů (součástí většiny instalací)
ext-json pro soubory stavu operací a datové části Git LFS API
ext-mbstring, deklarované v composer.json, takže Composer je při instalaci vyžaduje
ext-ctype pro ověření hashů (povoleno ve většině sestavení PHP, ale není deklarováno v composer.json)

Základní operace s úložištěm nevyžadují binární soubor git, FFI ani externí pomocné nástroje. Volitelné funkce mají další požadavky na běhové prostředí: spouštění hooků používá proc_open() a přenos SSH používá ext-ssh2, pokud je načteno, jinak spouští systémový binární soubor ssh přes proc_open().

Otevření existujícího úložiště

PHP

use Pitmaster\Pitmaster;

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

Tím se otevře úložiště v zadané cestě. Pitmaster vyhledá adresář .git (nebo vyřeší soubor .git u propojených pracovních stromů) a inicializuje databázi objektů, databázi odkazů a konfiguraci.

open(), init() a clone() přijímají jako poslední argument pole voleb:

PHP

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

Hooky se spouštějí ve výchozím nastavení. Pitmaster::processFreeOptions() vrací ['processes' => false, 'hooks' => false]; místní čtení a zápisy s takovým objektem nadále fungují.

Ověření, zda je cesta úložištěm

PHP

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

Inicializace nového úložiště

PHP

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

Tím se vytvoří struktura adresářů .git s objekty, odkazy, HEAD (ukazující na refs/heads/main) a výchozí konfigurací.

Chcete-li vytvořit úložiště SHA-256, předejte jako druhý argument formát objektů:

PHP

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

ID objektů v tomto úložišti mají 64 hexadecimálních znaků a konfigurace zaznamenává extensions.objectformat = sha256. Později otevřená úložiště načtou formát z této položky konfigurace.

Načtení commitu HEAD

PHP

$head = $repo->head();

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

Metoda head() vyhodnotí HEAD (následuje symbolické odkazy) a vrátí objekt Commit.

Výpis větví a štítků

PHP

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

Procházení historie commitů

PHP

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

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

Můžete také začít od konkrétního commitu:

PHP

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

Kontrola stavu pracovního stromu

PHP

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

Přidání souborů do indexu a vytvoření commitu

PHP

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

Jméno a e-mail autora se určují v tomto pořadí: proměnné prostředí PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, proměnné prostředí GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL, konstanty PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, vlastní .git/config úložiště (user.name a user.email) a nakonec Pitmaster <pitmaster@localhost>. Čte se pouze konfigurační soubor úložiště (a soubory, které zahrnuje), nikoli ~/.gitconfig. Autor commitu se určuje stejně z názvů *_COMMITTER_* a jako záložní možnost se použijí konstanty autora.

Výpočet rozdílů

PHP

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

Klonování vzdáleného úložiště

PHP

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

Tím se vyhledají odkazy, stáhne soubor pack, nastaví vzdálené sledovací větve a provede checkout výchozí větve. Adresy URL HTTP(S) používají chytrý přenos HTTP a při jeho selhání přecházejí na jednoduchý přenos HTTP; adresy URL SSH používají přenos SSH. Při mělkém klonování zadejte hloubku jako třetí argument: Pitmaster::clone($url, $path, 1).

Načtení libovolného objektu podle hashe

PHP

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

Konfigurace

Pitmaster respektuje nastavení .git/config úložiště pro informace o autorovi a vzdálené adresy URL. Výchozí globální hodnoty můžete nastavit také pomocí konstant PHP definovaných před spuštěním Pitmaster:

PHP

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

Konstanta	Výchozí hodnota	Účinek
`PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`	žádná	Identita autora (viz výše uvedené pořadí)
`PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL`	hodnoty autora	Identita autora commitu
`PITMASTER_HTTP_TIMEOUT`	`30`	Časový limit chytrého přenosu HTTP v sekundách (celé číslo)
`PITMASTER_MAX_DELTA_CHAIN`	`50`	Maximální hloubka řetězce rozdílů při čtení packů (celé číslo)
`PITMASTER_OBJECT_CACHE_ENTRIES`	`1024`	Objekty uchovávané v mezipaměti objektů v paměti
`PITMASTER_OBJECT_CACHE_BYTES`	`16M`	Limit velikosti mezipaměti objektů v bajtech
`PITMASTER_PACK_RESOLVED_CACHE_ENTRIES`	`4096`	Vyřešené objekty rozdílů ukládané do mezipaměti pro každý pack
`PITMASTER_PACK_RESOLVED_CACHE_BYTES`	`32M`	Limit velikosti této mezipaměti packů v bajtech
`PITMASTER_MAX_PACK_MEMORY`	žádná	Starší název limitu velikosti mezipaměti packů, používaný pouze tehdy, když není definováno `PITMASTER_PACK_RESOLVED_CACHE_BYTES`

Hodnoty v bajtech přijímají celé číslo nebo řetězec s příponou k, m nebo g ('256M'). Neplatné hodnoty se nahradí výchozí hodnotou.

Proměnné prostředí mají přednost před konstantami identity: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, odpovídajícími proměnnými PITMASTER_COMMITTER_* a také vlastními proměnnými gitu GIT_AUTHOR_* a GIT_COMMITTER_*. Přenos SSH čte proměnné PITMASTER_SSH_*, popsané v Protokolech.

Pro hashovací algoritmus neexistuje žádná konstanta. Formát objektů se zvolí při vytvoření úložiště (Pitmaster::init($path, 'sha256') nebo init --object-format=sha256 na CLI) a poté se načítá z konfigurace úložiště.