Darba sākšana

Instalēšana

Instalējiet Pitmaster, izmantojot Composer:

composer require pitmaster/pitmaster

Prasības

• PHP 8.2+ ar tikai lasāmām klasēm, uzskaitījumiem un konstruktora parametru veicināšanu
• ext-zlib objektu saspiešanai/atspiešanai (iebūvēts lielākajā daļā instalāciju)
• ext-json darbību stāvokļa failiem un Git LFS API datu kopām
• ext-mbstring, deklarēts composer.json, tāpēc Composer tas ir nepieciešams instalēšanas laikā
• ext-ctype jaucējvērtību validēšanai (iespējots lielākajā daļā PHP būvējumu, bet nav deklarēts composer.json)

Repozitorija pamatdarbībām nav nepieciešams git binārais fails, FFI vai ārējie palīgrīki. Izvēles funkcijām ir papildu izpildlaika prasības: āķu izpilde izmanto proc_open(), un SSH transports izmanto ext-ssh2, ja tas ir ielādēts, bet citādi palaiž sistēmas ssh bināro failu ar proc_open() palīdzību.

Atvērt esošu repozitoriju

use Pitmaster\Pitmaster;

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

Tas atver repozitoriju norādītajā ceļā. Pitmaster atrod direktoriju .git (vai atrisina failu .git saistītām darba kokām) un inicializē objektu datubāzi, atsauču datubāzi un konfigurāciju.

open(), init() un clone() kā pēdējo argumentu pieņem opciju masīvu:

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

Āķi tiek palaisti pēc noklusējuma. Pitmaster::processFreeOptions() atgriež ['processes' => false, 'hooks' => false]; lokālā lasīšana un rakstīšana ar šādu objektu turpina darboties.

Pārbaudīt, vai ceļš ir repozitorijs

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

Inicializēt jaunu repozitoriju

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

Tiek izveidota .git direktoriju struktūra ar objektiem, atsaucēm, HEAD (kas norāda uz refs/heads/main) un noklusējuma konfigurāciju.

Lai izveidotu SHA-256 repozitoriju, kā otro argumentu norādiet objektu formātu:

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

Objektu ID šajā repozitorijā ir 64 heksadecimālās rakstzīmes, un konfigurācijā ir norādīts extensions.objectformat = sha256. Vēlāk atvērtie repozitoriji formātu nolasa no šī konfigurācijas ieraksta.

Nolasīt HEAD commit

$head = $repo->head();

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

Metode head() atrisina HEAD (sekojot simboliskajām atsaucēm) un atgriež objektu Commit.

Uzskaitīt atzarus un tagus

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

Pārlūkot commit vēsturi

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

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

Varat arī sākt no konkrēta commit:

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

Pārbaudīt darba koka statusu

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

Pievienot failus indeksēšanai un izveidot commit

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

Autora vārds un e-pasts tiek noteikts šādā secībā: vides mainīgie PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, vides mainīgie GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL, konstantes PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, paša repozitorija .git/config (user.name un user.email) un visbeidzot Pitmaster <pitmaster@localhost>. Tiek lasīts tikai repozitorija konfigurācijas fails (un tajā iekļautie faili), nevis ~/.gitconfig. Commit veicējs tiek noteikts tādā pašā veidā, izmantojot *_COMMITTER_* nosaukumus, un, ja tie nav norādīti, tiek izmantotas autora konstantes.

Aprēķināt atšķirības

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

Klonēt attālinātu repozitoriju

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

Tiek atklātas atsauces, izgūts pakotnes fails, iestatīti attālināto atzaru izsekošanas atzari un pārbaudīts noklusējuma atzars. HTTP(S) URL izmanto viedo HTTP un, ja tas neizdodas, pārslēdzas uz vienkāršo HTTP; SSH URL izmanto SSH transportu. Seklai klonēšanai kā trešo argumentu norādiet dziļumu: Pitmaster::clone($url, $path, 1).

Nolasīt jebkuru objektu pēc jaucējvērtības

$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ācija

Pitmaster ievēro repozitorija .git/config autora informācijai un attālināto repozitoriju URL. Varat arī iestatīt globālās noklusējuma vērtības ar konstantēm PHP, kas definētas pirms Pitmaster izpildes:

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

Baitu vērtībām pieņem veselu skaitli vai virkni ar sufiksu k, m vai g ('256M'). Nederīgas vērtības aizstāj noklusējuma vērtība.

Vides mainīgie aizstāj identitātes konstantes: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, to PITMASTER_COMMITTER_* ekvivalenti un paša git mainīgie GIT_AUTHOR_* un GIT_COMMITTER_*. SSH transports nolasa PITMASTER_SSH_* mainīgos, kas aprakstīti sadaļā Protokoli.

Jaucējalgoritmam nav konstantes. Objektu formātu izvēlas, izveidojot repozitoriju (Pitmaster::init($path, 'sha256') vai init --object-format=sha256 sistēmā CLI), un pēc tam nolasa no repozitorija konfigurācijas.