# البدء

## التثبيت

ثبّت Pitmaster عبر Composer:

```bash
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()`.

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

```php
use Pitmaster\Pitmaster;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```php
$head = $repo->head();

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

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

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

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

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

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

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

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

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

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

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

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

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

يُحدَّد اسم المؤلف وبريده الإلكتروني بهذا الترتيب: متغيرا البيئة `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_*`، ويعود إلى ثوابت المؤلف.

## حساب الفروق

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

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

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

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

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

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

## الإعداد

يراعي Pitmaster إعداد `.git/config` الخاص بالمستودع لمعلومات المؤلف وعناوين URL البعيدة. يمكنك أيضًا تعيين القيم الافتراضية العامة باستخدام ثوابت PHP، المحددة قبل تشغيل 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');
```

| الثابت | القيمة الافتراضية | التأثير |
|----------|---------|--------|
| `PITMASTER_AUTHOR_NAME`، `PITMASTER_AUTHOR_EMAIL` | بلا | هوية المؤلف (راجع الترتيب أعلاه) |
| `PITMASTER_COMMITTER_NAME`، `PITMASTER_COMMITTER_EMAIL` | قيم المؤلف | هوية مُرسِل الالتزام |
| `PITMASTER_HTTP_TIMEOUT` | `30` | مهلة بروتوكول HTTP الذكي بالثواني (عدد صحيح) |
| `PITMASTER_MAX_DELTA_CHAIN` | `50` | الحد الأقصى لعمق سلسلة دلتا عند قراءة الحزم (عدد صحيح) |
| `PITMASTER_OBJECT_CACHE_ENTRIES` | `1024` | العناصر المحفوظة في ذاكرة التخزين المؤقت للعناصر |
| `PITMASTER_OBJECT_CACHE_BYTES` | `16M` | ميزانية بايتات ذاكرة تخزين العناصر المؤقتة |
| `PITMASTER_PACK_RESOLVED_CACHE_ENTRIES` | `4096` | عناصر دلتا المحلولة المخزنة مؤقتًا لكل حزمة |
| `PITMASTER_PACK_RESOLVED_CACHE_BYTES` | `32M` | ميزانية بايتات ذاكرة التخزين المؤقت لتلك الحزمة |
| `PITMASTER_MAX_PACK_MEMORY` | بلا | الاسم السابق لميزانية بايتات ذاكرة تخزين الحزمة المؤقتة، ويُستخدم فقط عند عدم تعريف `PITMASTER_PACK_RESOLVED_CACHE_BYTES` |

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

تتجاوز متغيرات البيئة ثوابت الهوية: `PITMASTER_AUTHOR_NAME`، `PITMASTER_AUTHOR_EMAIL`، `PITMASTER_AUTHOR_DATE`، ونظائر `PITMASTER_COMMITTER_*`، ومتغيرا `GIT_AUTHOR_*` و`GIT_COMMITTER_*` الخاصان بـ git. يقرأ ناقل SSH متغيرات `PITMASTER_SSH_*`، الموضحة في [البروتوكولات](https://pitmaster.inline0.dev/ar/docs/network/protocols).

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