# مرجع CLI يتضمن Pitmaster واجهة CLI تحاكي مجموعة فرعية من أوامر git. وهي تعمل على المستودع في مجلد العمل الحالي. ```bash ./vendor/bin/pitmaster [args...] ``` في تثبيت Composer، يكون البرنامج النصي `./vendor/bin/pitmaster`؛ ومنذ الإصدار 0.2.11 يعثر هناك على محمّل المشروع. وفي نسخة مستنسخة من مستودع Pitmaster نفسه، شغّل `./bin/pitmaster` بعد `composer install`. تستخدم الأمثلة أدناه `pitmaster` لأي من المسارين. يؤدي تشغيله بلا وسيطات إلى طباعة قائمة الأوامر. تُحل المراجعات كما في `Repository::resolve()`: `HEAD`، وأسماء الفروع والوسوم، وأسماء المراجع الكاملة، والتجزئات الكاملة، وتعبيرات `~N` / `^N`. لا تُقبل التجزئات المختصرة. لا تتوفر عمليات الاستنساخ والجلب والدفع إلا عبر PHP API. ## الأوامر ### `log` اعرض سجل الإيداعات، من الأحدث أولًا. ```bash # Default: last 10 commits pitmaster log # Limit the number of commits pitmaster log 25 pitmaster log -n 3 pitmaster log -n3 pitmaster log --max-count 3 pitmaster log --max-count=3 pitmaster log -3 # Commits that touch one file pitmaster log src/Repository.php pitmaster log -- src/Repository.php # Commits reachable from all refs, and one line per commit pitmaster log --all pitmaster log --oneline ``` أُضيفت صيغ حدود git (`-n N` و`-nN` و`--max-count N` و`--max-count=N` و`-N`) في الإصدار 0.2.11. والرقم المجرد اختصار خاص بـ Pitmaster لتحديد الحد. أما أول وسيطة أخرى فهي مرشح للمسار؛ وكل ما يأتي بعد `--` يُعامل على أنه المسار. وتطبع أي وسيطة أخرى تبدأ بـ `-` القيمة `fatal: unrecognized argument: ` ثم تنهي التنفيذ بالرمز 128. يتضمن الإخراج `commit ` (بالأصفر)، وسطر `Merge:` لإيداعات الدمج، و`Author:` مع الهوية الخام (الاسم والبريد الإلكتروني والطابع الزمني والمنطقة الزمنية)، ورسالة الإيداع بمسافة بادئة. تطبع `--oneline` القيمة `abc1234 Subject`. يطابق مرشح المسار مسار ملف واحدًا بعينه، ويفحص أحدث خمسة أضعاف الحد من الإيداعات فقط ([#7](https://github.com/inline0/pitmaster/issues/7)). ### `show` اعرض تفاصيل الإيداع والفرق بينه وبين الأصل الأول. ```bash # Show HEAD pitmaster show # Show a specific commit pitmaster show HEAD~3 pitmaster show v1.0.0 pitmaster show 3f2c1e0b9d6a4f8e7c5b2a1d0e9f8c7b6a5d4e3f ``` يعرض بيانات الإيداع الوصفية (مع سطر `Date:`) ثم فرقًا موحدًا. في حالة الوسم المشروح، يظهر رأس الوسم ورسالته أولًا. تُستخدم الألوان فقط عندما يكون stdout طرفية. وتُعرض إيداعات الدمج من دون فرق. ### `cat-file` اطبع المحتوى الخام لكائن git. ```bash pitmaster cat-file a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 ``` يأخذ تجزئة كاملة. ويطبع المحتوى المخزّن للكائن: الكتل والالتزامات والوسوم كنص، والأشجار بصيغتها الثنائية. بخلاف `git cat-file -p`، لا تُعرض الأشجار بتنسيق مقروء. ### `status` اعرض حالة شجرة العمل. ```bash pitmaster status pitmaster status --porcelain=v2 ``` المخرجات: ``` On branch main Changes to be committed: new file: src/Feature.php Changes not staged for commit: modified: src/Existing.php Untracked files: notes.txt ``` تظهر الملفات المُضافة إلى الفهرس باللون الأخضر، والملفات غير المُضافة أو غير المدمجة أو غير المتعقبة باللون الأحمر. يظهر قسم `Unmerged paths:` عند وجود تعارض أثناء الدمج. وتطبع حالة HEAD المنفصل `HEAD detached`، بينما تطبع الشجرة النظيفة `nothing to commit, working tree clean`. ويطبع `--porcelain=v2` مخرجات `Repository::statusPorcelainV2()`. ### `diff` اعرض التغييرات بين الفهرس وشجرة العمل (التغييرات غير المُضافة إلى الفهرس). ```bash # Unstaged changes pitmaster diff # Staged changes (index vs HEAD) pitmaster diff --cached pitmaster diff --staged # Choose the algorithm pitmaster diff --patience pitmaster diff --histogram pitmaster diff --minimal ``` المخرجات فرق موحد ملوّن، حتى عندما لا يكون stdout طرفية. وهي تطابق `git diff` للملفات النصية المعدّلة؛ أما الملفات الجديدة والمحذوفة والثنائية والمعاد تسميتها والمتغيرة الوضع فتُنسّق بشكل مختلف (راجع [Diff](https://pitmaster.inline0.dev/ar/docs/operations/diff)). لا يطبع `diff --cached` شيئًا قبل الالتزام الأول ([#5](https://github.com/inline0/pitmaster/issues/5)). ### `add` أضف الملفات إلى الفهرس للالتزام التالي. ```bash pitmaster add src/Feature.php pitmaster add src/Feature.php tests/FeatureTest.php README.md ``` تُقرأ الملفات من شجرة العمل، وتُكتب ككائنات كتلية، ويُحدّث الفهرس. الوسائط هي مسارات الملفات؛ ولا تُوسّع المجلدات و`.`. ### `commit` أنشئ التزامًا من الملفات المُضافة إلى الفهرس. ```bash pitmaster commit -m "Add new feature" ``` المخرجات: ``` [main abc1234] Add new feature ``` يلزم `-m`، إلا عند إكمال دمج أو انتقاء التزام أو تراجع أو إعادة تأسيس متوقفة، حيث تُستخدم الرسالة المُعدّة. تُحدّد هوية المؤلف والمُلتزِم من متغيرات البيئة والثوابت و`.git/config`، كما هو موضح في [البدء](https://pitmaster.inline0.dev/ar/docs/getting-started). ### `branch` اعرض الفروع أو أنشئ فرعًا جديدًا. ```bash # List all branches (current marked with *) pitmaster branch # Create a new branch from HEAD pitmaster branch feature/new-thing # Delete a branch pitmaster branch -d feature/old pitmaster branch -D feature/old ``` مخرجات عرض القائمة: ``` bugfix/typo feature/login * main ``` تطبع عملية الإنشاء `Created branch `، وتطبع عملية الحذف `Deleted branch `. يعمل `-d` و`-D` بالطريقة نفسها: لا يتحقق أي منهما من دمج الفرع، ويرفض كلاهما حذف الفرع المحدد حاليًا. ### `tag` اعرض الوسوم أو أنشئ وسمًا جديدًا. ```bash # List all tags pitmaster tag # Create a lightweight tag at HEAD pitmaster tag v1.0.0 # Create an annotated tag at HEAD pitmaster tag v2.0.0 -m "Release version 2.0.0" ``` تطبع عملية الإنشاء `Created tag `. ### `checkout` بدّل الفروع أو افصل HEAD. ```bash # Switch to a branch pitmaster checkout feature/login # Detach HEAD at a tag or commit pitmaster checkout v1.0.0 pitmaster checkout HEAD~2 ``` يحدّث HEAD والفهرس وشجرة العمل لتطابق الهدف، ويطبع `Switched to ''`. ويرفض التنفيذ إذا وُجدت تغييرات محلية أو ملفات غير متعقبة في مسارات تختلف بين الشجرتين. أما التغييرات غير المُلتزم بها في الملفات الأخرى المتعقبة، فيستبدلها بمحتوى الهدف، وهو ما يحتفظ به git عادةً ([#2](https://github.com/inline0/pitmaster/issues/2))؛ لذا أودِعها في التزام أو خزّنها مؤقتًا أولًا. ### `merge` ادمج فرعًا واحدًا أو أكثر في HEAD الحالي، أو تابع/ألغِ عملية دمج متوقفة بسبب تعارض. ```bash # Start a merge pitmaster merge feature/login # Merge with a strategy pitmaster merge -s ours feature/login # Octopus merge of several branches pitmaster merge feature/a feature/b # Continue after resolving conflicts pitmaster add a.txt pitmaster merge --continue # Abort and restore the pre-merge state pitmaster merge --abort ``` المخرجات عند النجاح: ``` Merge successful. ``` المخرجات عند التعارض (على stderr، ورمز الخروج 1): ``` CONFLICT in: src/File.php, src/Other.php ``` يقبل `-s` الوسائط `ours` و`ort` و`recursive`؛ ويستخدم كل من `ort` و`recursive` الدمج الافتراضي. مع `-s`، يطبع CLI `Merge successful.` وينتهي برمز 0 حتى إذا توقف الدمج بسبب تعارض ([#21](https://github.com/inline0/pitmaster/issues/21))، لذا تحقّق من `status` بعد ذلك. ينتهي `merge --continue` برمز 128 إذا لم تكن هناك عملية دمج جارية. ويؤدي دمج فرع سبق دمجه إلى إنشاء التزام دمج آخر ([#6](https://github.com/inline0/pitmaster/issues/6))، كما تُستبدل التغييرات غير المُلتزم بها في الملفات المتعقبة كما يحدث مع `checkout`. ### `cherry-pick` طبّق التزامًا فوق HEAD الحالي، أو تابع/ألغِ عملية متوقفة بسبب تعارض. ```bash # Start a cherry-pick pitmaster cherry-pick feature~1 # Continue after resolving conflicts pitmaster add a.txt pitmaster cherry-pick --continue # Abort and restore HEAD pitmaster cherry-pick --abort ``` لا يطبع شيئًا عند النجاح. ينتهي كل من `--continue` و`--abort` برمز 128 إذا لم تكن هناك عملية انتقاء التزام جارية. ### `revert` أنشئ التزام تراجع، أو تابع/ألغِ عملية متوقفة بسبب تعارض. ```bash # Start a revert pitmaster revert HEAD~1 # Continue after resolving conflicts pitmaster add a.txt pitmaster revert --continue # Abort and restore HEAD pitmaster revert --abort ``` لا يطبع شيئًا عند النجاح. ينتهي كل من `--continue` و`--abort` برمز 128 إذا لم تكن هناك عملية تراجع جارية. ### `rebase` أعِد تأسيس الفرع الحالي على مرجع آخر. ```bash # Start a rebase pitmaster rebase main # Continue after resolving conflicts pitmaster rebase --continue # Skip the current commit pitmaster rebase --skip # Abort and restore the original branch tip pitmaster rebase --abort ``` لا يطبع شيئًا عند النجاح. أما `--continue` و`--skip` و`--abort`، إذا لم تكن هناك عملية إعادة تأسيس جارية، فتطبع `fatal: no rebase in progress` وتنتهي برمز 128. ### `bisect` اعثر على الالتزام الذي أدخل تغييرًا باستخدام البحث الثنائي. ```bash # Start with a bad and a good revision; checks out and prints the first candidate pitmaster bisect start HEAD v1.0.0 # Mark the checked-out candidate (or a given revision) pitmaster bisect good pitmaster bisect bad pitmaster bisect bad HEAD~3 # End the session and return to the starting branch pitmaster bisect reset ``` تطبع `start` و`good` و`bad` التجزئة الكاملة للمرشح التالي، الذي يتم تحديده حاليًا. عندما يتبقى مشتبه به واحد، تُطبع التجزئة نفسها مرة أخرى: فهذا هو أول التزام معيب. بخلاف git، لا تُطبع خلاصة «هذا هو أول التزام معيب». ### `stash` احفظ تغييرات دليل العمل واستعدها. ```bash # Save current changes (push) pitmaster stash pitmaster stash push pitmaster stash push "Work in progress on login" pitmaster stash save "Work in progress on login" # Apply and remove the top stash entry pitmaster stash pop # Apply without removing pitmaster stash apply # List stash entries pitmaster stash list # Drop the top stash entry pitmaster stash drop ``` الرسالة هي الوسيط الذي يلي `push` أو `save`؛ أما `-m` فغير مدعوم وسيُخزّن كنص الرسالة. يستخدم كل من `pop` و`apply` و`drop` دائمًا `stash@{0}`. وتطبع هذه الأوامر `Saved working directory to stash abc1234` و`Applied and dropped stash` و`Applied stash` و`Dropped stash`. مخرجات قائمة التخزين المؤقت: ``` stash@{0}: On main: Work in progress on login stash@{1}: WIP on main: abc1234 Add new feature ``` عند وجود أكثر من إدخال، يُبقي `drop` و`pop` الإدخال حاليًا في القائمة ([#10](https://github.com/inline0/pitmaster/issues/10))، ويستبدل `apply` التغييرات غير المُلتزم بها في الملفات التي لا تمسها اللقطة المؤقتة ([#11](https://github.com/inline0/pitmaster/issues/11)). ### `blame` اعرض مؤلف كل سطر في ملف عند HEAD. ```bash pitmaster blame src/Repository.php ``` المخرجات: ``` a1b2c3d4 (Jane Smith ) ) f5e6d7c8 (Ann Lee 1700) declare(strict_types=1); ``` يعرض كل سطر أول 8 أحرف من تجزئة الالتزام وأول 30 حرفًا من هوية المؤلف (`Name timestamp timezone`)، دون حشو. ### `grep` ابحث في محتويات الملفات ضمن شجرة HEAD الحالية. ```bash pitmaster grep "function merge" pitmaster grep -i -E "h.llo" ``` المخرجات: ``` src/Repository.php:2257: public function merge(string $branch, string $strategy = 'recursive'): MergeResult src/Merge/ThreeWayMerge.php:23: public static function merge( ``` يجب أن تسبق الخيارات النمط: - `-i`، `--ignore-case`: مطابقة دون تمييز حالة الأحرف - `-E`، `--extended-regexp`، `--regex`: تعامل مع النمط كتعبير نمطي PCRE المخرجات نص عادي `path:line:content` بلا ألوان. ### `reflog` اعرض إدخالات reflog، الأحدث أولًا. ```bash # HEAD reflog (default: 10 entries) pitmaster reflog # Another ref, a custom limit, and a format pitmaster reflog show refs/heads/main pitmaster reflog -n 5 pitmaster reflog --format="%h %gs" ``` التنسيق الافتراضي هو `%gd: %gs` (`HEAD@{0}: commit: Add feature`). العناصر النائبة المدعومة: `%gd` و`%gD` (المحدد)، و`%gs` (الرسالة)، و`%H` و`%h` (التجزئة الجديدة كاملة ومختصرة). تقبل الحدود `-n N` و`-nN` و`--max-count N`؛ ويطبع `-n 0` جميع الإدخالات. لا تسجل المستودعات التي ينشئها `pitmaster init` سجلات reflog ما لم تُضبط `core.logallrefupdates` على `true` في `.git/config` ([#8](https://github.com/inline0/pitmaster/issues/8))، لذا لا يطبع `reflog` فيها شيئًا حتى يتم ذلك. ### `refs` اعرض جميع المراجع مع تجزئاتها. ```bash pitmaster refs ``` المخرجات: ``` abc123def456... refs/heads/main 789012abc345... refs/heads/feature/login def456789012... refs/tags/v1.0.0 ``` تُطبع التجزئات كاملة. ### `reset` أعِد ضبط HEAD إلى التزام محدد. ```bash # Mixed reset (HEAD + index, default) pitmaster reset HEAD~1 pitmaster reset --mixed HEAD~1 # Soft reset (HEAD only) pitmaster reset --soft HEAD~1 # Hard reset (HEAD + index + worktree) pitmaster reset --hard HEAD~3 ``` يلزم تحديد مراجعة. المخرجات: ``` HEAD is now at abc1234 ``` ### `init` أنشئ مستودعًا جديدًا. هذا هو الأمر الوحيد الذي لا يحتاج إلى مستودع موجود. ```bash # Initialize in the current directory pitmaster init # Initialize at a specific path pitmaster init /path/to/new-project # Create a SHA-256 repository pitmaster init --object-format=sha256 pitmaster init /path/to/new-project --object-format=sha256 ``` المخرجات: ``` Initialized empty Pitmaster repository in /path/to/new-project/.git/ ``` يقبل `--object-format` الخيار `sha1` (الافتراضي) و`sha256`. ## رموز الخروج | الرمز | المعنى | |------|---------| | 0 | نجاح | | 1 | خطأ في الأمر: خطأ استخدام، أمر غير معروف، فشل العملية (`error: `)، أو توقف الدمج بسبب تعارض | | 128 | ليس مستودع git (`fatal: `)، أو وسيطة `log` غير معروفة، أو استخدام `--continue` / `--abort` / `--skip` دون وجود عملية جارية |