مرجع CLI

يتضمن Pitmaster واجهة CLI تحاكي مجموعة فرعية من أوامر git. وهي تعمل على المستودع في مجلد العمل الحالي.

./vendor/bin/pitmaster <command> [args...]

في تثبيت Composer، يكون البرنامج النصي ./vendor/bin/pitmaster؛ ومنذ الإصدار 0.2.11 يعثر هناك على محمّل المشروع. وفي نسخة مستنسخة من مستودع Pitmaster نفسه، شغّل ./bin/pitmaster بعد composer install. تستخدم الأمثلة أدناه pitmaster لأي من المسارين. يؤدي تشغيله بلا وسيطات إلى طباعة قائمة الأوامر.

تُحل المراجعات كما في Repository::resolve(): HEAD، وأسماء الفروع والوسوم، وأسماء المراجع الكاملة، والتجزئات الكاملة، وتعبيرات ~N / ^N. لا تُقبل التجزئات المختصرة. لا تتوفر عمليات الاستنساخ والجلب والدفع إلا عبر PHP API.

الأوامر

log

اعرض سجل الإيداعات، من الأحدث أولًا.

# 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: <arg> ثم تنهي التنفيذ بالرمز 128.

يتضمن الإخراج commit <hash> (بالأصفر)، وسطر Merge: لإيداعات الدمج، وAuthor: مع الهوية الخام (الاسم والبريد الإلكتروني والطابع الزمني والمنطقة الزمنية)، ورسالة الإيداع بمسافة بادئة. تطبع --oneline القيمة abc1234 Subject. يطابق مرشح المسار مسار ملف واحدًا بعينه، ويفحص أحدث خمسة أضعاف الحد من الإيداعات فقط (#7).

show

اعرض تفاصيل الإيداع والفرق بينه وبين الأصل الأول.

# 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.

pitmaster cat-file a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

يأخذ تجزئة كاملة. ويطبع المحتوى المخزّن للكائن: الكتل والالتزامات والوسوم كنص، والأشجار بصيغتها الثنائية. بخلاف git cat-file -p، لا تُعرض الأشجار بتنسيق مقروء.

status

اعرض حالة شجرة العمل.

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

اعرض التغييرات بين الفهرس وشجرة العمل (التغييرات غير المُضافة إلى الفهرس).

# 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). لا يطبع diff --cached شيئًا قبل الالتزام الأول (#5).

add

أضف الملفات إلى الفهرس للالتزام التالي.

pitmaster add src/Feature.php
pitmaster add src/Feature.php tests/FeatureTest.php README.md

تُقرأ الملفات من شجرة العمل، وتُكتب ككائنات كتلية، ويُحدّث الفهرس. الوسائط هي مسارات الملفات؛ ولا تُوسّع المجلدات و..

commit

أنشئ التزامًا من الملفات المُضافة إلى الفهرس.

pitmaster commit -m "Add new feature"

المخرجات:

[main abc1234] Add new feature

يلزم -m، إلا عند إكمال دمج أو انتقاء التزام أو تراجع أو إعادة تأسيس متوقفة، حيث تُستخدم الرسالة المُعدّة. تُحدّد هوية المؤلف والمُلتزِم من متغيرات البيئة والثوابت و.git/config، كما هو موضح في البدء.

branch

اعرض الفروع أو أنشئ فرعًا جديدًا.

# 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 <name>، وتطبع عملية الحذف Deleted branch <name>. يعمل -d و-D بالطريقة نفسها: لا يتحقق أي منهما من دمج الفرع، ويرفض كلاهما حذف الفرع المحدد حاليًا.

tag

اعرض الوسوم أو أنشئ وسمًا جديدًا.

# 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 <name>.

checkout

بدّل الفروع أو افصل HEAD.

# 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 '<target>'. ويرفض التنفيذ إذا وُجدت تغييرات محلية أو ملفات غير متعقبة في مسارات تختلف بين الشجرتين. أما التغييرات غير المُلتزم بها في الملفات الأخرى المتعقبة، فيستبدلها بمحتوى الهدف، وهو ما يحتفظ به git عادةً (#2)؛ لذا أودِعها في التزام أو خزّنها مؤقتًا أولًا.

merge

ادمج فرعًا واحدًا أو أكثر في HEAD الحالي، أو تابع/ألغِ عملية دمج متوقفة بسبب تعارض.

# 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)، لذا تحقّق من status بعد ذلك. ينتهي merge --continue برمز 128 إذا لم تكن هناك عملية دمج جارية. ويؤدي دمج فرع سبق دمجه إلى إنشاء التزام دمج آخر (#6)، كما تُستبدل التغييرات غير المُلتزم بها في الملفات المتعقبة كما يحدث مع checkout.

cherry-pick

طبّق التزامًا فوق HEAD الحالي، أو تابع/ألغِ عملية متوقفة بسبب تعارض.

# 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

أنشئ التزام تراجع، أو تابع/ألغِ عملية متوقفة بسبب تعارض.

# 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

أعِد تأسيس الفرع الحالي على مرجع آخر.

# 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

اعثر على الالتزام الذي أدخل تغييرًا باستخدام البحث الثنائي.

# 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

احفظ تغييرات دليل العمل واستعدها.

# 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)، ويستبدل apply التغييرات غير المُلتزم بها في الملفات التي لا تمسها اللقطة المؤقتة (#11).

blame

اعرض مؤلف كل سطر في ملف عند HEAD.

pitmaster blame src/Repository.php

المخرجات:

a1b2c3d4 (Jane Smith <jane@example.com> ) <?php
a1b2c3d4 (Jane Smith <jane@example.com> )
f5e6d7c8 (Ann Lee <ann@example.com> 1700) declare(strict_types=1);

يعرض كل سطر أول 8 أحرف من تجزئة الالتزام وأول 30 حرفًا من هوية المؤلف (Name <email> timestamp timezone)، دون حشو.

grep

ابحث في محتويات الملفات ضمن شجرة HEAD الحالية.

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، الأحدث أولًا.

# 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)، لذا لا يطبع reflog فيها شيئًا حتى يتم ذلك.

refs

اعرض جميع المراجع مع تجزئاتها.

pitmaster refs

المخرجات:

abc123def456... refs/heads/main
789012abc345... refs/heads/feature/login
def456789012... refs/tags/v1.0.0

تُطبع التجزئات كاملة.

reset

أعِد ضبط HEAD إلى التزام محدد.

# 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

أنشئ مستودعًا جديدًا. هذا هو الأمر الوحيد الذي لا يحتاج إلى مستودع موجود.

# 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.

رموز الخروج