البدء

التثبيت

ثبّت Pitmaster عبر Composer:

composer require pitmaster/pitmaster

المتطلبات

• PHP 8.2+ مع الأصناف للقراءة فقط والتعدادات وترقية المُنشئ
• ext-zlib لضغط العناصر وفك ضغطها (مضمّن في معظم عمليات التثبيت)
• ext-json لملفات حالة العمليات وبيانات API الخاصة بـGit LFS
• ext-mbstring، المُعلن في composer.json، لذا يتطلبه Composer وقت التثبيت
• ext-ctype للتحقق من التجزئات (مفعّل في معظم إصدارات PHP، لكنه غير مُعلن في composer.json)

لا تتطلب عمليات المستودع الأساسية الملف التنفيذي git أو FFI أو أدوات مساعدة خارجية. للميزات الاختيارية متطلبات تشغيل إضافية: يستخدم تنفيذ الخطافات proc_open()، ويستخدم نقل SSH ext-ssh2 عند تحميله، وإلا يشغّل الملف التنفيذي ssh الخاص بالنظام عبر proc_open().

فتح مستودع موجود

use Pitmaster\Pitmaster;

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

يفتح هذا المستودع في المسار المحدد. يحدد Pitmaster موقع دليل .git (أو يحل ملف .git لأشجار العمل المرتبطة) ويهيئ قاعدة بيانات العناصر وقاعدة بيانات المراجع والإعدادات.

تقبل open() وinit() وclone() مصفوفة خيارات كوسيط أخير:

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

تعمل الخطافات افتراضيًا. يعيد Pitmaster::processFreeOptions() القيمة ['processes' => false, 'hooks' => false]؛ وتظل عمليات القراءة والكتابة المحلية تعمل على هذا المقبض.

التحقق مما إذا كان المسار مستودعًا

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

تهيئة مستودع جديد

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

ينشئ هذا بنية دليل .git بما فيها العناصر والمراجع وHEAD (الذي يشير إلى refs/heads/main) وإعداد افتراضي.

لإنشاء مستودع SHA-256، مرّر تنسيق العناصر كوسيط ثانٍ:

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

تتكون معرّفات العناصر في ذلك المستودع من 64 حرفًا سداسيًا عشريًا، ويسجل الإعداد extensions.objectformat = sha256. وتقرأ المستودعات التي تُفتح لاحقًا التنسيق من مدخل الإعداد هذا.

قراءة التزام HEAD

$head = $repo->head();

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

تحل الطريقة head() مرجع HEAD (باتباع المراجع الرمزية) وتعيد كائن Commit.

سرد الفروع والعلامات

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

استعراض سجل الالتزامات

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

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

يمكنك أيضًا البدء من التزام محدد:

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

التحقق من حالة شجرة العمل

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

تجهيز الملفات وإنشاء التزام

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

يُحدَّد اسم المؤلف وبريده الإلكتروني بهذا الترتيب: متغيرا البيئة PITMASTER_AUTHOR_NAME وPITMASTER_AUTHOR_EMAIL، ثم متغيرا البيئة GIT_AUTHOR_NAME وGIT_AUTHOR_EMAIL، ثم ثوابت PITMASTER_AUTHOR_NAME وPITMASTER_AUTHOR_EMAIL، ثم إعداد .git/config الخاص بالمستودع (user.name وuser.email)، وأخيرًا Pitmaster <pitmaster@localhost>. لا يُقرأ إلا ملف إعدادات المستودع (والملفات التي يضمّنها)، وليس ~/.gitconfig. ويُحدَّد المُرسِل بالطريقة نفسها باستخدام الأسماء *_COMMITTER_*، ويعود إلى ثوابت المؤلف.

حساب الفروق

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

استنساخ مستودع بعيد

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

يكتشف هذا المراجع، ويجلب ملف الحزمة، ويعدّ فروع تتبع بعيدة، ويسحب الفرع الافتراضي. تستخدم عناوين URL الخاصة بـHTTP(S) بروتوكول HTTP الذكي وتعود إلى HTTP الغبي؛ وتستخدم عناوين SSH نقل SSH. مرّر عمقًا كوسيط ثالث للاستنساخ السطحي: Pitmaster::clone($url, $path, 1).

قراءة أي عنصر حسب التجزئة

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

الإعداد

يراعي Pitmaster إعداد .git/config الخاص بالمستودع لمعلومات المؤلف وعناوين URL البعيدة. يمكنك أيضًا تعيين القيم الافتراضية العامة باستخدام ثوابت PHP، المحددة قبل تشغيل Pitmaster:

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

تقبل قيم البايتات عددًا صحيحًا أو سلسلة تنتهي باللاحقة k أو m أو g ('256M'). تعود القيم غير الصالحة إلى القيمة الافتراضية.

تتجاوز متغيرات البيئة ثوابت الهوية: PITMASTER_AUTHOR_NAME، PITMASTER_AUTHOR_EMAIL، PITMASTER_AUTHOR_DATE، ونظائر PITMASTER_COMMITTER_*، ومتغيرا GIT_AUTHOR_* وGIT_COMMITTER_* الخاصان بـ git. يقرأ ناقل SSH متغيرات PITMASTER_SSH_*، الموضحة في البروتوكولات.

لا يوجد ثابت لخوارزمية التجزئة. يُختار تنسيق العناصر عند إنشاء المستودع (Pitmaster::init($path, 'sha256') أو init --object-format=sha256 على CLI) ويُقرأ لاحقًا من إعدادات المستودع.