مقدمة

Pitmaster مكتبة خالصة بـPHP تقرأ مستودعات Git وتكتب فيها مباشرةً. لا تشغّل عمليات المستودع الأساسية الملف التنفيذي git كعملية خارجية ولا تستخدم FFI. نُفّذ نموذج عناصر Git وتنسيق ملفات الحزم وتنسيق الفهرس ونقل HTTP الذكي باستخدام PHP.

سبب وجود Pitmaster

عادةً ما تشغّل تطبيقات PHP التي تتفاعل مع مستودعات Git الملف التنفيذي git كعملية خارجية. ينجح هذا، لكنه يفرض اعتمادًا قويًا على تثبيت git، ويثير مخاوف أمنية تتعلق بـexec() وproc_open()، ويصعّب نشر التطبيق في البيئات المقيدة (حاويات بلا git، واستضافة مشتركة، ووظائف دون خادم).

يزيل Pitmaster الاعتماد على git لتنفيذ أعمال المستودع الأساسية. يمكن لتطبيق PHP قراءة سجل الالتزامات وإنشاء الالتزامات وحساب الفروق والتحقق من الحالة والدفع إلى المستودعات البعيدة عبر HTTP الذكي باستخدام الوظائف المضمنة في PHP فقط. الخطافات ونقل SSH هما الاستثناء؛ فكلاهما يشغّل عمليات، ويمكن تعطيلهما لكل مقبض مستودع (راجع الخطافات).

ما الذي يقدمه

• يقرأ الكائنات المنفصلة ويكتبها (blob وtree وcommit وtag)
• يقرأ ملفات الحزم ويحسم سلاسل الفروق (OFS_DELTA وREF_DELTA)
• يكتب ملفات الحزم لعمليات الشبكة
• يقرأ الفهرس/منطقة التجهيز ويكتبها (تنسيقات v2 وv3 وv4)
• يقرأ المراجع ويكتبها (الفروع والوسوم وHEAD وpacked-refs وreftable)
• يحسب الفروق (باستخدام خوارزميات Myers وPatience وHistogram وMinimal) بتنسيق موحد من git
• ينفذ عمليات دمج ثلاثية الأطراف مع اكتشاف التعارضات
• يتتبع رسوم الالتزامات (السجل والنسب وقاعدة الدمج)
• يتواصل عبر بروتوكول Git الذكي من HTTP (الاستنساخ والجلب والدفع)
• يدعم أشجار العمل والوحدات الفرعية والتخزين المؤقت والخطافات وGit LFS

المتطلبات

• PHP 8.2 أو أحدث
• إضافة zlib (مضمّنة في جميع عمليات تثبيت PHP تقريبًا)
• إضافة json
• إضافة mbstring (مُعلنة في composer.json، لذا يتطلبها Composer وقت التثبيت)
• إضافة ctype (للتحقق من تجزئات العناصر؛ مفعّلة في معظم إصدارات PHP، لكنها غير مُعلنة في composer.json)

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

مثال سريع

use Pitmaster\Pitmaster;

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

// Read the current HEAD commit
$head = $repo->head();
echo $head->message;

// List branches
foreach ($repo->branches() as $branch) {
    echo $branch . "\n";
}

// Check status
foreach ($repo->status() as $entry) {
    echo "{$entry->path}: {$entry->index->value}{$entry->worktree->value}\n";
}

// Create a commit
$repo->add('src/Feature.php');
$commitId = $repo->commit('Add new feature');

ابدأ بـ البدء، ثم استخدم API، وCLI، والعمليات للاطلاع على بقية الجوانب. يشرح الاختبار كيفية التحقق من Pitmaster مقابل git.