Memulai

Lihat sebagai Markdown Edit di GitHub Dokumentasi di bfe242f

Instalasi

Instal Pitmaster melalui Composer:

Shell

composer require pitmaster/pitmaster

Persyaratan

PHP 8.2+ dengan kelas readonly, enum, dan promosi konstruktor
ext-zlib untuk kompresi/dekompresi objek (bawaan di sebagian besar instalasi)
ext-json untuk file status operasi dan payload Git LFS API
ext-mbstring, dideklarasikan di composer.json, sehingga Composer memerlukannya saat instalasi
ext-ctype untuk validasi hash (diaktifkan di sebagian besar build PHP, tetapi tidak dideklarasikan di composer.json)

Operasi inti repositori tidak memerlukan biner git, FFI, atau helper eksternal. Fitur opsional memiliki persyaratan runtime tambahan: eksekusi hook menggunakan proc_open(), dan transport SSH menggunakan ext-ssh2 saat dimuat, atau menjalankan biner sistem ssh melalui proc_open() jika tidak.

Membuka repositori yang sudah ada

PHP

use Pitmaster\Pitmaster;

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

Ini membuka repositori di jalur yang diberikan. Pitmaster menemukan direktori .git (atau me-resolve file .git untuk worktree tertaut) lalu menginisialisasi basis data objek, basis data ref, dan konfigurasi.

open(), init(), dan clone() menerima array opsi sebagai argumen terakhir:

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

Hook dijalankan secara default. Pitmaster::processFreeOptions() mengembalikan ['processes' => false, 'hooks' => false]; operasi baca dan tulis lokal tetap berfungsi pada handle seperti itu.

Memeriksa apakah jalur merupakan repositori

PHP

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

Menginisialisasi repositori baru

PHP

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

Ini membuat struktur direktori .git dengan objek, refs, HEAD (menunjuk ke refs/heads/main), dan konfigurasi default.

Untuk membuat repositori SHA-256, berikan format objek sebagai argumen kedua:

PHP

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

ID objek di repositori itu terdiri dari 64 karakter heksadesimal, dan konfigurasi mencatat extensions.objectformat = sha256. Repositori yang dibuka kemudian mengambil format tersebut dari entri konfigurasi itu.

Membaca commit HEAD

PHP

$head = $repo->head();

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

Metode head() me-resolve HEAD (mengikuti ref simbolis) dan mengembalikan objek Commit.

Mencantumkan branch dan tag

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

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

Anda juga dapat memulai dari commit tertentu:

PHP

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

Memeriksa status pohon kerja

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

Menyiapkan file dan membuat commit

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

Nama dan email penulis ditentukan dengan urutan berikut: variabel lingkungan PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, variabel lingkungan GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL, konstanta PITMASTER_AUTHOR_NAME / PITMASTER_AUTHOR_EMAIL, .git/config milik repositori (user.name dan user.email), lalu Pitmaster <pitmaster@localhost>. Hanya file konfigurasi repositori (beserta file yang disertakannya) yang dibaca, bukan ~/.gitconfig. Identitas committer ditentukan dengan cara yang sama dari nama *_COMMITTER_* dan menggunakan konstanta penulis sebagai nilai cadangan.

Menghitung diff

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

Mengklon repositori remote

PHP

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

Ini menemukan refs, mengambil file pack, menyiapkan branch pelacakan remote, dan melakukan checkout branch default. URL HTTP(S) menggunakan HTTP pintar dan beralih ke HTTP biasa jika perlu; URL SSH menggunakan transport SSH. Berikan kedalaman sebagai argumen ketiga untuk klon dangkal: Pitmaster::clone($url, $path, 1).

Membaca objek apa pun berdasarkan hash

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

Konfigurasi

Pitmaster menggunakan .git/config repositori untuk informasi penulis dan URL remote. Anda juga dapat menetapkan nilai default global dengan konstanta PHP, yang didefinisikan sebelum Pitmaster dijalankan:

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	Default	Dampak
`PITMASTER_AUTHOR_NAME`, `PITMASTER_AUTHOR_EMAIL`	none	Identitas penulis (lihat urutan di atas)
`PITMASTER_COMMITTER_NAME`, `PITMASTER_COMMITTER_EMAIL`	nilai penulis	Identitas committer
`PITMASTER_HTTP_TIMEOUT`	`30`	Batas waktu HTTP pintar dalam detik (bilangan bulat)
`PITMASTER_MAX_DELTA_CHAIN`	`50`	Kedalaman rantai delta maksimum saat membaca pack (bilangan bulat)
`PITMASTER_OBJECT_CACHE_ENTRIES`	`1024`	Jumlah objek yang disimpan dalam cache objek di memori
`PITMASTER_OBJECT_CACHE_BYTES`	`16M`	Batas byte cache objek
`PITMASTER_PACK_RESOLVED_CACHE_ENTRIES`	`4096`	Objek delta yang telah di-resolve dan di-cache per pack
`PITMASTER_PACK_RESOLVED_CACHE_BYTES`	`32M`	Batas byte cache pack tersebut
`PITMASTER_MAX_PACK_MEMORY`	none	Nama lama untuk batas byte cache pack, hanya digunakan jika `PITMASTER_PACK_RESOLVED_CACHE_BYTES` tidak ditentukan

Nilai byte menerima bilangan bulat atau string dengan akhiran k, m, atau g ('256M'). Nilai yang tidak valid akan menggunakan nilai default.

Variabel lingkungan mengesampingkan konstanta identitas: PITMASTER_AUTHOR_NAME, PITMASTER_AUTHOR_EMAIL, PITMASTER_AUTHOR_DATE, padanannya PITMASTER_COMMITTER_*, serta variabel GIT_AUTHOR_* dan GIT_COMMITTER_* milik git. Transport SSH membaca variabel PITMASTER_SSH_*, yang dijelaskan di Protokol.

Tidak ada konstanta untuk algoritma hash. Format objek dipilih saat repositori dibuat (Pitmaster::init($path, 'sha256') atau init --object-format=sha256 pada CLI), lalu dibaca dari konfigurasi repositori setelahnya.