سجل Git وأوامر المساعدة: افحص مستودعك وابحث فيه وافهمه

السجل المفيد في Git ليس مجرد قائمة بالالتزامات القديمة، بل هو سجل تقني يمكنه توضيح متى تغيّر سلوك معين، ولماذا اتُّخذ قرار ما، وما الملفات التي تأثرت، ومن عدّل سطرًا آخر مرة، وكيف تطور المشروع إلى حالته الحالية.

يوفر Git عدة أدوات متكاملة لاستكشاف هذا السجل. يتنقل git log بين الالتزامات، ويفحص git show كائنًا محددًا، ويقارن git diff بين الحالات، ويربط git blame الأسطر بالالتزامات، بينما يسجل git reflog تحركات المراجع المحلية. ويتضمن Git أيضًا نظام مساعدة مدمجًا وشاملًا، لذلك لا تحتاج إلى حفظ كل خيار قبل أن تبدأ العمل بفاعلية.

يشرح هذا الدليل هذه الأوامر من خلال مستودع عملي، ثم يوضح كيفية الجمع بين الفلاتر، وصياغة revision، وسجل المسارات، وعمليات البحث في المحتوى، وأدوات التوثيق للإجابة عن أسئلة تطوير حقيقية.

ما الذي ستتعلمه؟

  • كيفية تنظيم سجل Git على شكل رسم بياني للالتزامات.

  • كيفية قراءة مخرجات السجل المختصرة والمفصلة.

  • كيفية تصفية السجل بحسب المؤلف والتاريخ والرسالة والمسار وحالة الدمج.

  • كيفية تنسيق السجلات للبشر والتقارير والسكربتات.

  • كيفية فحص التزام واحد باستخدام git show.

  • كيفية مقارنة الالتزامات والفروع والملفات والنطاقات باستخدام git diff.

  • كيفية عمل أسماء revision مثل HEAD~2 وA..B وA...B.

  • كيفية البحث عن الالتزام الذي أضاف أو حذف أو غيّر شيفرة محددة.

  • كيفية تتبع ملف عبر عمليات إعادة التسمية.

  • كيفية استخدام git blame بمسؤولية.

  • كيفية استخدام reflog المحلي لاستعادة المراجع التي تحركت مؤخرًا.

  • كيفية استخدام المساعدة المختصرة، وصفحات الدليل، والأدلة المفاهيمية، وأدوات اكتشاف الأوامر في Git.

السجل رسم بياني للالتزامات، وليس مجلد نسخ احتياطية

يخزن كل التزام عادي مرجعًا إلى لقطة من المشروع، وبيانات وصفية، ورسالة، والتزامًا أبًا واحدًا أو أكثر.

يبدو السجل الخطي البسيط كما يلي:

A---B---C---D  main

يشير كل التزام إلى الأب الخاص به. ويمكن لـ Git أن يبدأ من D ويتحرك إلى الخلف عبر C وB وA.

عندما تتفرع الفروع ثم تُدمج لاحقًا، يتحول السجل إلى رسم بياني:

A---B---C-------F  main
         \     /
          D---E    feature

يملك التزام الدمج F أبوين. ويمكن لأوامر السجل عرض الرسم، أو اتباع جميع الآباء، أو التركيز على مسار فرع محدد.

يفسر نموذج الرسم البياني هذا سبب قبول أدوات سجل Git لنقاط بداية ونطاقات revision بدل الاكتفاء بعرض الالتزامات وفق الوقت.

إنشاء مستودع للتدرب

ينشئ المستودع التالي سجلًا كافيًا لتوضيح الفلاتر، وتغييرات الملفات، والتفرع، والدمج.

على macOS أو Linux أو Git Bash

mkdir git-history-demo
cd git-history-demo
git init -b main

cat > app.txt <<'EOF'
Task Notes
الإصدار: 1
EOF

git add app.txt
git commit -m "إنشاء تطبيق ملاحظات المهام"

cat > README.md <<'EOF'
# Task Notes

مشروع صغير للتدرب على سجل Git.
EOF

git add README.md
git commit -m "إضافة توثيق المشروع"

cat >> app.txt <<'EOF'
التخزين: ملف محلي
EOF

git add app.txt
git commit -m "توثيق وضع التخزين المحلي"

git switch -c feature/search

cat > search.txt <<'EOF'
البحث عن المهام بحسب الكلمة المفتاحية.
EOF

git add search.txt
git commit -m "إضافة وصف البحث بالكلمة المفتاحية"

cat >> README.md <<'EOF'

## البحث

يمكن البحث عن المهام باستخدام كلمة مفتاحية.
EOF

git add README.md
git commit -m "توثيق البحث في المهام"

git switch main

cat >> app.txt <<'EOF'
التنسيق: نص عادي
EOF

git add app.txt
git commit -m "توثيق تنسيق تخزين المهام"

git merge --no-ff feature/search -m "دمج ميزة البحث في المهام"

على PowerShell

New-Item -ItemType Directory git-history-demo
Set-Location git-history-demo
git init -b main

@"
Task Notes
الإصدار: 1
"@ | Set-Content app.txt

git add app.txt
git commit -m "إنشاء تطبيق ملاحظات المهام"

@"
# Task Notes

مشروع صغير للتدرب على سجل Git.
"@ | Set-Content README.md

git add README.md
git commit -m "إضافة توثيق المشروع"

"التخزين: ملف محلي" | Add-Content app.txt
git add app.txt
git commit -m "توثيق وضع التخزين المحلي"

git switch -c feature/search

"البحث عن المهام بحسب الكلمة المفتاحية." | Set-Content search.txt
git add search.txt
git commit -m "إضافة وصف البحث بالكلمة المفتاحية"

@"

## البحث

يمكن البحث عن المهام باستخدام كلمة مفتاحية.
"@ | Add-Content README.md

git add README.md
git commit -m "توثيق البحث في المهام"

git switch main

"التنسيق: نص عادي" | Add-Content app.txt
git add app.txt
git commit -m "توثيق تنسيق تخزين المهام"

git merge --no-ff feature/search -m "دمج ميزة البحث في المهام"

تحقق من المستودع:

git status
git log --oneline --graph --decorate --all

ابدأ باستخدام git log

الأمر الأساسي هو:

git log

يبدأ Git افتراضيًا من نهاية الفرع الحالي ويتحرك عبر الالتزامات الأب التي يمكن الوصول إليها. وتشمل المخرجات المعتادة:

  • المعرّف الكامل للالتزام.

  • المؤلف.

  • تاريخ المؤلف.

  • رسالة الالتزام.

يعرض Git النتائج عادة من خلال pager. ومن المفاتيح الشائعة داخله:

  • Space أو Page Down: الانتقال إلى الأمام.

  • b: الانتقال إلى الخلف في أشهر برامج pager.

  • /text: البحث داخل المخرجات المعروضة.

  • n: الانتقال إلى نتيجة البحث التالية.

  • q: الخروج.

إذا بدا أن الطرفية توقفت بعد git log، فغالبًا هي تنتظر إدخالًا داخل pager. اضغط q.

سجل مختصر باستخدام --oneline

git log --oneline

يطبع هذا الأمر التزامًا واحدًا في كل سطر باستخدام معرّف مختصر وعنوان الالتزام.

مثال:

f84b2d1 دمج ميزة البحث في المهام
29d41ea توثيق تنسيق تخزين المهام
d00394c توثيق البحث في المهام
8021abc إضافة وصف البحث بالكلمة المفتاحية
29c22f8 توثيق وضع التخزين المحلي
b012890 إضافة توثيق المشروع
44aa731 إنشاء تطبيق ملاحظات المهام

ستختلف المعرّفات لديك.

يُعد --oneline مريحًا للتنقل، لكنه يخفي المؤلفين والتواريخ وأجسام الرسائل والمحتوى المتغير. استخدمه كنظرة عامة، لا كطريقة العرض الوحيدة للسجل.

عرض الرسم البياني للفروع

git log --oneline --graph --decorate --all

تعمل الخيارات التالية معًا:

  • يرسم --graph تمثيلًا نصيًا لعلاقات الآباء.

  • يعرض --decorate أسماء الفروع والعلامات والمراجع الأخرى بجوار الالتزامات.

  • يبدأ --all من جميع المراجع بدل الفرع الحالي فقط.

مثال على الشكل:

*   f84b2d1 (HEAD -> main) دمج ميزة البحث في المهام
|\
| * d00394c (feature/search) توثيق البحث في المهام
| * 8021abc إضافة وصف البحث بالكلمة المفتاحية
* | 29d41ea توثيق تنسيق تخزين المهام
|/
* 29c22f8 توثيق وضع التخزين المحلي
* b012890 إضافة توثيق المشروع
* 44aa731 إنشاء تطبيق ملاحظات المهام

يوضح الرسم بنية السجل. ولا تستطيع تواريخ الالتزامات وحدها تفسير علاقات الأبوة بين الالتزامات بصورة موثوقة.

تحديد عدد الالتزامات

لعرض أحدث ثلاثة التزامات:

git log -3

الصيغة الطويلة المكافئة:

git log --max-count=3

ادمجه مع الصيغة المختصرة:

git log -5 --oneline

عرض الملفات وإحصاءات الأسطر

لعرض الملفات المتغيرة وعدد الأسطر:

git log --stat

لعرض رموز حالة الملفات فقط:

git log --name-status

تشمل رموز الحالة المعتادة:

  • A: تمت الإضافة.

  • M: تم التعديل.

  • D: تم الحذف.

  • R: تمت إعادة التسمية عندما يكتشفها Git.

لعرض أسماء الملفات من دون رموز الحالة:

git log --name-only

لعرض patch كامل لكل التزام محدد:

git log -p

إذا كان المستودع كبيرًا، فقيّد مخرجات patch بأحدث الالتزامات:

git log -p -2

تنسيق مخصص للسجل

يوفر Git تنسيقات pretty جاهزة:

git log --pretty=short
git log --pretty=full
git log --pretty=fuller
git log --pretty=reference

ولإنشاء تنسيق خاص، استخدم --format:

git log --format="%h | %an | %ad | %s" --date=short

من placeholders المفيدة:

Placeholderالمعنى
%Hالمعرّف الكامل للالتزام
%hالمعرّف المختصر للالتزام
%anاسم المؤلف
%aeبريد المؤلف
%cnاسم منشئ الالتزام
%adتاريخ المؤلف
%cdتاريخ منشئ الالتزام
%arتاريخ المؤلف بصيغة نسبية
%sعنوان الالتزام
%bمتن رسالة الالتزام
%dزخارف المراجع
%Pمعرّفات الآباء

يمكن استخدام تنسيق مناسب للفريق مثل:

git log --graph --date=short \
  --format="%C(auto)%h%d %s %C(dim white)(%an, %ad)%C(reset)" \
  --all

تعتمد placeholders الخاصة بالألوان على دعم الطرفية. لا تحلل المخرجات البشرية المزخرفة والملونة داخل السكربتات.

تصفية السجل بحسب التاريخ

لعرض الالتزامات بعد تاريخ معين:

git log --since="2026-01-01"

لعرض الالتزامات قبل تاريخ معين:

git log --until="2026-06-30"

استخدم أوصافًا نسبية:

git log --since="2 weeks ago"
git log --since="yesterday"
git log --until="last month"

في السكربتات والتقارير القابلة للتكرار، فضّل تنسيقات التاريخ الصريحة وتحقق من افتراضات المنطقة الزمنية.

ادمج الحدين:

git log --since="2026-01-01" --until="2026-03-01" --oneline

التصفية بحسب Author أو Committer

للبحث بحسب هوية المؤلف:

git log --author="Jane"

تُعامل القيمة على أنها pattern، لذلك قد تطابق اسمًا أو بريدًا إلكترونيًا.

للبحث بحسب هوية منشئ الالتزام:

git log --committer="Alex"

قد يختلف المؤلف عن منشئ الالتزام بعد عمليات مثل rebase أو تطبيق patch أو cherry-pick.

افحص البيانات الوصفية الكاملة لالتزام واحد:

git log -1 --format=fuller

التصفية بحسب رسالة الالتزام

للبحث داخل رسائل الالتزام:

git log --grep="search"

للبحث من دون حساسية لحالة الأحرف:

git log --grep="storage" -i

للبحث عن عدة patterns:

git log --grep="fix" --grep="bug"

تطابق عدة خيارات --grep عادة عندما يطابق واحد منها على الأقل. استخدم --all-match عندما يجب أن تطابق جميع patterns المحددة وفق قواعد التصفية في الأمر.

يفيد البحث في الرسائل فقط عندما تكون رسائل الالتزام واضحة. تجعل الرسائل الغامضة التحقيق في السجل أكثر صعوبة.

تصفية التزامات الدمج وغير الدمج

لعرض التزامات الدمج فقط:

git log --merges --oneline

لاستبعاد التزامات الدمج:

git log --no-merges --oneline

لاتباع مسار first-parent:

git log --first-parent --oneline

يفيد --first-parent على فروع الدمج الرئيسية لأنه يبرز تسلسل الدمجات الأساسي بدل الدخول إلى كل فرع موضوعي مدموج.

لا يحذف السجل الأصلي، بل يغيّر طريقة اجتيازه وعرضه.

عرض سجل ملف أو مجلد واحد

ضع -- قبل المسار:

git log -- README.md

الصيغة المختصرة:

git log --oneline -- README.md

لعرض patch الذي أثر في الملف:

git log -p -- README.md

لعرض سجل مجلد:

git log --oneline -- src/

تزيل علامتا الشرطة الالتباس بين revision والمسار.

تتبع ملف عبر إعادة التسمية

لملف واحد، استخدم:

git log --follow -- path/to/file

وأضف patch:

git log --follow -p -- path/to/file

يحاول --follow مواصلة السجل إلى ما قبل إعادة تسمية ملف واحد. ويعتمد اكتشاف إعادة التسمية على تشابه المحتوى، لا على بيانات إعادة تسمية دائمة؛ لذلك قد تتأثر النتائج عند حدوث تغييرات كبيرة في المحتوى بالتزامن مع إعادة التسمية.

وعندما تكون إعادة التسمية واضحة، افحص أيضًا مخرجات name-status:

git log --name-status --follow -- path/to/file

عرض السجل من الأقدم إلى الأحدث

git log --reverse --oneline

يفيد ذلك عند دراسة كيفية بناء ميزة من أول التزاماتها.

ادمجه مع مسار:

git log --reverse -p -- README.md

فحص التزام واحد باستخدام git show

يعرض git show معلومات عن كائن واحد أو أكثر من كائنات Git. وعند تمرير التزام إليه، يعرض عادة رسالة الالتزام وdiff النصي.

لعرض الالتزام الحالي:

git show

لعرض التزام محدد:

git show 29c22f8

لعرض ملخص الإحصاءات:

git show --stat 29c22f8

لعرض الأسماء والحالات فقط:

git show --name-status 29c22f8

لعرض البيانات الوصفية من دون patch:

git show --no-patch --format=fuller 29c22f8

لفحص ملف كما كان مخزنًا داخل التزام محدد:

git show 29c22f8:app.txt

يقرأ هذا الأمر المحتوى التاريخي من دون تبديل الفرع أو تعديل شجرة العمل.

الفرق بين git log وgit show

الأمرالغرض الأساسي
git logالتنقل والتصفية ضمن سلسلة أو رسم بياني من الالتزامات
git showفحص كائنات محددة، وخصوصًا التزام واحد وpatch الخاص به

استخدم git log للعثور على الالتزام المناسب، ثم git show لدراسته بالتفصيل.

مقارنة الحالات باستخدام git diff

يجيب git diff عن سؤال مختلف عن git log. فهو يقارن المحتوى بين حالتين.

شجرة العمل مقابل منطقة التجهيز

git diff

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

منطقة التجهيز مقابل HEAD

git diff --staged

يعرض الالتزام التالي المقترح.

شجرة العمل مقابل HEAD

git diff HEAD

يجمع التغييرات المجهزة وغير المجهزة مقارنة بالالتزام الحالي.

التزام مقابل التزام آخر

git diff commitA commitB

يقارن Git اللقطتين اللتين تحددهما revision.

ملف واحد فقط بين revision

git diff commitA commitB -- README.md

ملخص بدل patch الكامل

git diff --stat commitA commitB
git diff --name-status commitA commitB

فهم أسماء Revision

تقبل أوامر Git كثيرة revisions. ويمكن تسمية revision باستخدام فرع أو tag أو معرّف التزام أو مرجع خاص أو تعبير نسبي.

أسماء الفروع والعلامات

git show main
git show feature/search
git show v1.0.0

HEAD

يشير HEAD عادة إلى الالتزام الحالي الذي جرى checkout له:

git show HEAD

صياغة الأب باستخدام ^

الأب الأول لـ HEAD:

HEAD^
HEAD^1

الأب الثاني لالتزام دمج:

HEAD^2

تُعد صيغة الأب الثاني مهمة لأن التزامات الدمج تملك أكثر من أب.

أسلاف First-Parent باستخدام ~

خطوتان إلى الخلف عبر first-parent من HEAD:

HEAD~2

في سجل خطي، يصل HEAD^^ وHEAD~2 إلى الالتزام نفسه. أما في سجلات الدمج، فيعبّر تكرار first-parent واختيار أب محدد عن نيتين مختلفتين.

موقع Checkout السابق

@{-1}

يشير هذا عادة إلى الفرع أو الالتزام الذي جرى checkout له سابقًا، وقد يكون مفيدًا مع أوامر مثل git switch.

نطاقات Revision: ‏A..B

النطاق ذو النقطتين:

A..B

يحدد الالتزامات التي يمكن الوصول إليها من B ولا يمكن الوصول إليها من A.

مثال:

git log --oneline main..feature/search

يسأل هذا الأمر: ما الالتزامات الموجودة في feature/search وغير الموجودة في main؟

اعكس النطاق:

git log --oneline feature/search..main

يعرض Git الآن الالتزامات الموجودة في main وغير الموجودة في فرع الميزة.

الاتجاه مهم.

الفرق المتماثل: ‏A...B

بالنسبة إلى git log، تحدد صيغة النقاط الثلاث:

A...B

الالتزامات التي يمكن الوصول إليها من أحد الطرفين، ولكن ليس من الطرفين معًا.

git log --left-right --oneline main...feature/search

يضع --left-right علامة توضّح الطرف الذي ينتمي إليه كل التزام.

يفيد ذلك عندما تتباعد الفروع وتريد رؤية الالتزامات الخاصة بكل طرف.

النقطتان والنقاط الثلاث تعنيان أشياء مختلفة في git diff

يمكن أن تعتمد صياغة revision على سياق الأمر.

الأمر:

git diff A B

يقارن لقطة A بلقطة B.

أما الصيغة:

git diff A..B

فهي عمليًا طريقة أخرى لكتابة مقارنة النقطتين النهائيتين نفسها في git diff.

لكن:

git diff A...B

يقارن merge base بين A وB مع B. وهو يجيب عن سؤال قريب من: ما الذي غيّره الفرع الموجود على اليمين منذ تباعد الفرعين؟

لا تفترض أن صياغة النطاق تملك معنى الاختيار نفسه في كل أمر. اقرأ توثيق الأمر عندما تكون الدقة مهمة.

العثور على الالتزام الذي أضاف أو حذف نصًا

استخدم خيار pickaxe وهو -S:

git log -S"التخزين: ملف محلي" --oneline

يبحث هذا عن الالتزامات التي تغيّر فيها عدد مرات ظهور النص الدقيق.

لعرض patch:

git log -S"التخزين: ملف محلي" -p

لقصر البحث على مسار:

git log -S"التخزين: ملف محلي" -p -- app.txt

يفيد هذا عند طرح أسئلة مثل:

  • متى أُضيف اسم هذه الدالة؟

  • أي التزام أزال مفتاح الإعداد هذا؟

  • متى ظهرت رسالة الخطأ هذه أول مرة؟

البحث داخل الأسطر المتغيرة باستخدام -G

استخدم -G عندما يجب أن تطابق الأسطر المضافة أو المحذوفة تعبيرًا نمطيًا:

git log -G"التخزين:.*ملف" --oneline -p

الفرق العملي:

  • يبحث -Stext عن تغير عدد مرات ظهور string.

  • يبحث -Gregex عن أسطر مضافة أو محذوفة تطابق regular expression.

بحسب طبيعة التغيير، قد يعثر أحدهما على التزام لا يعثر عليه الآخر. ابدأ بالسؤال الذي تريد الإجابة عنه، ثم افحص نتائج patch.

تتبع سجل دالة أو نطاق أسطر

يمكن لـ git log -L تتبع تطور نطاق أسطر أو نمط دالة مدعوم داخل ملف.

مثال باستخدام أرقام الأسطر:

git log -L 1,3:app.txt

يمكن استخدام صيغ تعتمد على الدالة مع اللغات والأنماط المدعومة:

git log -L :function_name:path/to/file

تُعد هذه الميزة قوية عند دراسة تطور دالة واحدة من دون قراءة كل التزامات الملف كاملًا.

تختلف الصياغة والتعرف على الدوال بحسب الملف المستهدف وdiff drivers المضبوطة في Git، لذلك راجع git help log للحصول على الصيغ الدقيقة.

البحث في المحتوى المتتبع باستخدام git grep

يبحث git grep افتراضيًا عن patterns داخل الملفات المتتبعة في شجرة العمل:

git grep "Task Notes"

لعرض أرقام الأسطر:

git grep -n "Task Notes"

للبحث داخل tree تاريخية:

git grep "التخزين" HEAD~2

للبحث داخل مسارات محددة فقط:

git grep -n "البحث" -- "*.md"

يبحث git grep في المحتوى، بينما يبحث git log -S و-G في تاريخ تغييرات المحتوى.

استخدام git blame لتتبع الأسطر

نفّذ:

git blame app.txt

يضيف Git إلى كل سطر معلومات عن الالتزام الذي عدله آخر مرة، بما يشمل المعرّف والمؤلف والتاريخ ورقم السطر.

لقصر النتيجة على أسطر محددة:

git blame -L 1,3 app.txt

لتجاهل التغييرات التي تقتصر على المسافات عند الحاجة:

git blame -w app.txt

ولاكتشاف الأسطر المنقولة أو المنسوخة عند الحاجة:

git blame -M -C app.txt

قد تجعل هذه الخيارات التحليل أكثر تكلفة، خصوصًا في السجلات الكبيرة.

استخدم blame كنقطة بداية، لا كحكم نهائي

قد لا يكون آخر من عدّل السطر هو الشخص الذي صمم السلوك. فقد يصبح التزام تنسيق، أو نقل ملف، أو refactoring آلي، أو حل تعارض هو التغيير الأخير المسجل.

يكون التحقيق المسؤول كالتالي:

  1. تشغيل git blame لتحديد التزام مرشح.

  2. فحصه باستخدام git show.

  3. قراءة رسالة الالتزام وpatch المحيط بها.

  4. فحص سجل الملف الأقدم باستخدام git log -p -- path.

  5. البحث عن issue أو pull request مرتبطة عند توفرها.

استخدم السجل لفهم السياق، لا لإلقاء اللوم الشخصي.

فحص سجل المراجع المحلية باستخدام git reflog

تعرض سجلات الفروع الالتزامات التي يمكن الوصول إليها عبر تاريخ الفرع. أما reflog فيسجل متى تحركت المراجع المحلية، مثل نهايات الفروع وHEAD.

نفّذ:

git reflog

مثال على الشكل:

f84b2d1 HEAD@{0}: merge feature/search: Merge made by the 'ort' strategy.
29d41ea HEAD@{1}: checkout: moving from feature/search to main
d00394c HEAD@{2}: commit: توثيق البحث في المهام

يمكن أن تساعد سجلات reflog على إيجاد الالتزامات بعد عمليات مثل:

  • إرجاع فرع إلى الخلف باستخدام reset.

  • استبدال الالتزامات بواسطة rebase.

  • حذف فرع محليًا.

  • الانتقال بين عدة التزامات ونسيان موقع سابق.

  • استبدال الالتزام السابق بواسطة amend.

اعرض الموقع القديم المحدد:

git show HEAD@{2}

أنشئ فرع استعادة قبل إجراء المزيد من التغييرات:

git branch recovery HEAD@{2}

قيود reflog المهمة

  • reflog محلي لكل clone من المستودع.

  • يملك clone لدى مطور آخر reflog خاصًا به.

  • تُحفظ السجلات وفق سياسات الانتهاء والصيانة، وليس إلى الأبد.

  • لا يُعد reflog بديلًا عن العمل المسجل أو النسخ البعيدة أو النسخ الاحتياطية.

  • لا يمكن استعادة محتوى الملفات غير المسجل تلقائيًا من خلال reflog.

استخدم reflog بسرعة عندما تشك في أن التزامًا أصبح unreachable.

تلخيص المساهمين باستخدام git shortlog

لتجميع عناوين الالتزامات بحسب المؤلف:

git shortlog

لعرض عدد الالتزامات وأسماء المؤلفين:

git shortlog -sn

لتضمين عناوين البريد:

git shortlog -sne

في بعض السياقات، حدّد revision مثل:

git shortlog -sn HEAD

يفيد shortlog في ملاحظات الإصدارات وملخصات المساهمات، لكن اختلافات الهوية قد تقسّم الشخص نفسه إلى عدة إدخالات. ويمكن للمشروع استخدام ملف .mailmap لتوحيد الأسماء وعناوين البريد المعروفة.

العثور على Regression باستخدام git bisect

عندما تعرف أن التزامًا معينًا جيد وأن التزامًا لاحقًا سيئ، ينفذ git bisect بحثًا ثنائيًا داخل السجل.

ابدأ:

git bisect start

علّم الالتزام الحالي على أنه سيئ:

git bisect bad

علّم التزامًا أقدم معروفًا بأنه جيد:

git bisect good <good-commit>

ينتقل Git إلى نقطة وسطية. اختبرها ثم علّمها:

git bisect good
# أو
git bisect bad

كرر العملية حتى يحدد Git أول التزام سيئ.

أنهِ العملية وعد إلى الحالة الأصلية:

git bisect reset

يمكن أيضًا استخدام أوامر اختبار آلية مع bisect، لكن يجب أن تعيد نتيجة نجاح أو فشل بصورة موثوقة.

استخدام نظام المساعدة المدمج في Git

يوفر Git عدة مستويات من المساعدة.

ملخص قصير للخيارات

git log -h
git diff -h
git blame -h

تطبع صيغة -h ملخصًا مختصرًا للاستخدام داخل الطرفية. وهي مفيدة عندما تتذكر الأمر ولا تتذكر اسم خيار معين.

صفحة الدليل الكاملة

git help log
git log --help

تفتح هذه الصيغ التوثيق الكامل للأمر باستخدام عارض المساعدة المضبوط.

صيغة الويب

git help --web log

يطلب هذا فتح دليل HTML داخل المتصفح عندما تدعم البيئة ذلك.

عرض الأوامر الشائعة

git help

عند عدم تحديد أمر، يعرض Git الملخص العام والأوامر المستخدمة كثيرًا.

عرض جميع الأوامر المتاحة

git help --all

عرض الأدلة المفاهيمية

git help --guides

من أمثلة التوثيق المفاهيمي المفيد:

git help revisions
git help gitrevisions
git help gitglossary
git help gitignore
git help gitattributes
git help gitcli

عرض متغيرات الإعداد

git help --config

يعطي هذا ملخصًا قابلًا للبحث لمتغيرات إعداد Git.

تعلم قراءة صفحة دليل Git

تحتوي صفحة دليل Git عادة على الأقسام التالية:

  • Name: وصف من سطر واحد.

  • Synopsis: صيغ الأمر المقبولة.

  • Description: نموذج الأمر وسلوكه.

  • Options: الخيارات والوسائط.

  • Examples: تركيبات عملية.

  • Configuration: المتغيرات التي تؤثر في الأمر.

  • See Also: أوامر وأدلة مرتبطة.

تستخدم صياغة Synopsis اختصارات مكثفة:

  • تعني الأقواس المربعة مثل [option] عادة أن العنصر اختياري.

  • تمثل الأقواس الزاوية مثل <commit> قيمًا ستدخلها أنت.

  • تشير النقاط الثلاث إلى التكرار أو تعدد القيم.

  • يشير الخط العمودي عادة إلى البدائل.

  • تفصل -- الخيارات أو revisions عن المسارات.

لا تلصق الأقواس الزاوية حرفيًا إلا إذا كانت جزءًا من مثال آمن في shell.

البحث داخل المساعدة

عندما يُفتح الدليل داخل pager، ابحث باستخدام:

/pattern

أمثلة:

/--author
/pretty
/revision range

اضغط n للانتقال إلى النتيجة التالية وq للخروج في أشهر بيئات pager.

غالبًا ما تكون هذه الطريقة أسرع من قراءة الدليل منذ البداية.

اكتشاف الأوامر من دون تخمين

ابدأ بفئات الأوامر العامة:

git help
git help --all
git help --guides

ثم اطلب الاستخدام المختصر:

git log -h

وأخيرًا افتح التوثيق الكامل للأمر المحدد:

git help log

تقلل هذه الخطوات الثلاث من التجارب العشوائية بالأوامر.

إنشاء Aliases آمنة للسجل

يمكن لاختصار رسومي تقليل الكتابة المتكررة:

git config --global alias.lg \
"log --graph --decorate --oneline --all"

ثم نفّذ:

git lg

اختصار أكثر تفصيلًا:

git config --global alias.hist \
"log --graph --date=short --format=%h%d%x20%s%x20[%an,%x20%ad] --all"

Aliases أدوات مساعدة، وليست بديلًا عن فهم الأوامر الأصلية. ستستخدم التوثيقات وأعضاء الفريق عادة أسماء الأوامر القياسية.

تحقيق عملي: متى أُضيف إعداد معين؟

السؤال: متى دخل النص التخزين: ملف محلي إلى المشروع؟

1. البحث عن تغير في عدد الظهور

git log -S"التخزين: ملف محلي" --oneline -- app.txt

2. فحص الالتزام المرشح

git show <commit>

3. قراءة السجل القريب للملف

git log -p -- app.txt

4. فحص الملف قبل الالتزام وبعده

git show <commit>^:app.txt
git show <commit>:app.txt

يعطي هذا المسار أدلة بدل الاعتماد على آخر نسبة لسطر فقط.

تحقيق عملي: ما الذي تغير في فرع ميزة؟

قبل دمج الفرع:

git log --oneline main..feature/search
git diff --stat main...feature/search
git diff main...feature/search

يعرض log الالتزامات الخاصة بفرع الميزة. ويعرض diff ذو النقاط الثلاث التغييرات التي أُجريت على جهة الميزة منذ merge base مع main.

افحص أيضًا الرسم البياني للفروع:

git log --graph --decorate --oneline --all

تحقيق عملي: من عدّل السطر المسبب للمشكلة آخر مرة؟

افترض أن السطر 3 من app.txt مشكوك فيه.

git blame -L 3,3 app.txt

انسخ المعرّف المرشح ثم افحصه:

git show <commit>

ابحث عن تغييرات أقدم في المنطقة نفسها:

git log -p -- app.txt

وابحث عن النص نفسه:

git log -S"التخزين:" -p -- app.txt

تكون الأدلة المجمعة أكثر موثوقية من التوقف عند مخرجات blame.

تحقيق عملي: استعادة التزام بعد reset

افترض أن فرعًا محليًا أُرجع إلى الخلف وأن التزامًا حديثًا لم يعد يظهر في مخرجات log العادية.

1. فحص Reflog

git reflog --date=local

2. فحص الإدخال المرشح

git show HEAD@{1}

3. الحفاظ عليه

git branch recovery-before-reset HEAD@{1}

4. التحقق

git log --oneline --graph --decorate --all

أنشئ فرع استعادة قبل متابعة التجارب. إدخالات reflog ليست سجلات أرشيف دائمة.

أخطاء شائعة في قراءة السجل

افتراض أن git log يعرض كل التزامات المستودع

يبدأ git log العادي من revision الحالية ويعرض الالتزامات التي يمكن الوصول إليها. قد تحتوي فروع أخرى على التزامات لا يمكن الوصول إليها من الفرع الحالي. استخدم نقطة بداية مناسبة أو --all.

قراءة السجل بحسب التاريخ فقط

سجل Git رسم بياني للآباء. يمكن تغيير تواريخ المؤلفين، ويمكن لـ rebase إعادة كتابة الالتزامات، وقد تحتوي الفروع على أوقات متداخلة.

الخلط بين A..B وB..A

في نطاق log ذي النقطتين، يمثل الطرف الأيمن جهة الالتزامات المضمنة. يؤدي عكس الطرفين إلى تغيير النتيجة.

افتراض أن النقاط الثلاث تملك المعنى نفسه في كل مكان

يجيب git log A...B وgit diff A...B عن سؤالين مرتبطين لكن مختلفين.

استخدام git blame لإسناد الخطأ إلى شخص

يعرض blame أصل السطر وفق السجل، وليس المسؤولية أو ملكية التصميم أو النية.

البحث داخل رسائل الالتزام فقط

قد تكون رسالة التغيير المطلوب سيئة. استخدم فلاتر المسارات و-S و-G وdiff وblame كأدلة إضافية.

توقع وجود reflog في كل مكان وإلى الأبد

reflog محلي وتنتهي إدخالاته وفق سياسات الصيانة.

تحليل المخرجات البشرية في الأتمتة

قد تحتوي التنسيقات البشرية على ألوان وزخارف وتعريب ومسافات متغيرة. استخدم تنسيقات وفواصل مخصصة للآلة داخل السكربتات.

نسيان Pager

عندما تبدو المخرجات متجمدة، اضغط q قبل افتراض أن Git فشل.

أفضل الممارسات لقراءة سجل Git

  • ابدأ باستخدام git status لمعرفة الفرع الحالي وحالة العمل.

  • استخدم الرسم البياني لفهم بنية الفروع.

  • قيّد السجل بحسب المسار أو التاريخ أو المؤلف أو الرسالة قبل إضافة patch كامل.

  • استخدم git show لفحص الالتزامات المرشحة واحدًا واحدًا.

  • قارن اللقطات باستخدام git diff بدل التخمين من الرسائل.

  • استخدم -S و-G للتحقيق في تغييرات المحتوى.

  • تعامل مع git blame بوصفه نقطة دخول إلى السياق.

  • أنشئ فرع استعادة عندما يكشف reflog عن التزام مهم.

  • استخدم المساعدة المدمجة قبل نسخ أوامر مدمرة من أمثلة غير مرتبطة.

  • اكتب رسائل التزام واضحة لتسريع التحقيقات المستقبلية.

مرجع أوامر السجل

الأمرالغرض
git logالتنقل في سجل الالتزامات انطلاقًا من revision الحالية
git log --onelineعرض قائمة مختصرة بالالتزامات
git log --graph --decorate --allعرض بنية المستودع ومراجعه
git log -pعرض patch للالتزامات المحددة
git log --statعرض إحصاءات الملفات والأسطر
git log -- pathقصر السجل على مسار
git log --follow -- fileمحاولة تتبع ملف واحد عبر إعادة التسمية
git log --author="name"التصفية بحسب هوية المؤلف
git log --grep="text"التصفية بحسب pattern في رسالة الالتزام
git log -S"text" -pالعثور على التزامات تغيّر فيها عدد مرات ظهور string
git log -G"regex" -pالعثور على التزامات تحوي أسطرًا متغيرة تطابق pattern
git show revisionفحص كائن أو التزام محدد
git diff A Bمقارنة لقطتين
git blame fileإرفاق كل سطر بآخر التزام عدّله
git reflogعرض تحركات المراجع المحلية
git shortlog -sn HEADتلخيص عدد الالتزامات بحسب المؤلف
git grep -n "text"البحث في المحتوى المتتبع
git bisect startبدء بحث ثنائي عن regression

مرجع أوامر المساعدة

الأمرالغرض
git command -hعرض ملخص مختصر للاستخدام والخيارات
git help commandفتح دليل الأمر الكامل
git command --helpفتح توثيق الأمر الكامل نفسه
git help --web commandطلب توثيق HTML
git helpعرض الأوامر الشائعة والملخص العام
git help --allعرض الأوامر المتاحة
git help --guidesعرض الأدلة المفاهيمية
git help --configعرض متغيرات الإعداد
git help revisionsقراءة توثيق صياغة revision والنطاقات
git help gitglossaryقراءة تعريفات مصطلحات Git

قائمة التحقق للتحقيق في السجل

عند التحقيق في تغيير، اسأل:

  • من أي فرع أو revision يجب أن يبدأ السجل؟

  • هل أحتاج إلى جميع الفروع أم الالتزامات التي يمكن الوصول إليها من الفرع الحالي فقط؟

  • هل يمكن قصر البحث على مسار؟

  • هل أبحث عن رسالة أو مؤلف أو تاريخ أو string دقيق أو pattern لأسطر متغيرة؟

  • هل أحتاج إلى قائمة التزامات أم إلى مقارنة لقطات؟

  • هل يجب تضمين التزامات الدمج؟

  • هل من الممكن أن الملف أُعيدت تسميته؟

  • هل يحدد blame تغييرًا آليًا أو تغيّر تنسيق فقط؟

  • هل ما زال من الممكن أن يظهر التزام محلي مفقود في reflog؟

  • هل حافظت على الالتزام المرشح قبل تشغيل المزيد من أوامر إعادة كتابة السجل؟

الأسئلة الشائعة

لماذا لا يعرض git log التزامًا من فرع آخر؟

يعرض git log العادي الالتزامات التي يمكن الوصول إليها من revision البداية الحالية. استخدم اسم الفرع الآخر مباشرة أو أضف --all.

ما الفرق بين git log وgit reflog؟

يتحرك git log عبر سلالة الالتزامات، بينما يسجل git reflog تحركات المراجع المحلية مثل HEAD ونهايات الفروع.

كيف أرى ما الذي غيّره التزام معين؟

نفّذ git show <commit>. أضف --stat لملخص أو --name-status للمسارات المتغيرة.

كيف أرى ملفًا كما كان في التزام قديم؟

استخدم git show <commit>:path/to/file.

كيف أعرف متى أُضيفت دالة؟

جرّب git log -S"functionName" -p -- path. واستخدم -G عندما يناسب البحث بتعبير نمطي داخل الأسطر المتغيرة السؤال بصورة أفضل.

لماذا لا يعرض git diff شيئًا؟

قد تكون الحالات التي تقارنها متطابقة، أو قد تكون التغييرات مجهزة. استخدم git diff --staged للمحتوى المجهز، وحدد revisions للمقارنات التاريخية.

ما معنى HEAD~3؟

يشير إلى الالتزام الذي تصل إليه بعد اتباع first-parent ثلاث مرات انطلاقًا من HEAD.

ما معنى main..feature؟

بالنسبة إلى تنقل log، يحدد الالتزامات التي يمكن الوصول إليها من feature ولا يمكن الوصول إليها من main.

هل يستطيع git blame تتبع الملفات المعاد تسميتها؟

يملك blame خيارات لاكتشاف الأسطر المنقولة والمنسوخة، لكن التحقيق التاريخي يعمل غالبًا بصورة أفضل عند دمج blame مع git log --follow وgit show وسجل المسار.

هل يستطيع Reflog استعادة تغييرات غير مسجلة؟

ليس بصورة موثوقة. يتتبع reflog تحركات المراجع، ويفيد أساسًا في الالتزامات ومواقع المراجع التي وُجدت محليًا.

أي أمر مساعدة يجب استخدامه أولًا؟

استخدم git command -h للتذكير السريع بالخيارات، واستخدم git help command عندما تحتاج إلى السلوك الكامل أو الصياغة أو تفاصيل الإعداد.

الخلاصة

يصبح سجل Git أكثر فائدة عندما تتعامل معه بوصفه دليلًا. يمنحك السجل المختصر اتجاهًا عامًا، ويشرح الرسم البياني علاقات الأصل، وتقلل الفلاتر الضوضاء، ويكشف git show الالتزامات الفردية، ويقارن git diff اللقطات بدقة.

في التحقيقات الأعمق، تشرح نطاقات revision اختلافات الفروع، ويحدد -S و-G تغييرات المحتوى، ويتتبع سجل الملف تطوره، ويقدم blame مصدرًا مرشحًا للتغيير، وقد يكشف reflog مراجع محلية تحركت مؤخرًا.

لا تحتاج إلى حفظ كل خيار. فنظام المساعدة المدمج في Git جزء من مسار العمل. استخدم المساعدة المختصرة للتذكير، والأدلة الكاملة للسلوك الدقيق، والأدلة المفاهيمية عندما تكون صياغة revision أو نماذج الأوامر غير واضحة.

ستركز المقالة التالية على فروع Git وعمليات الدمج، بما يشمل إنشاء الفروع، والتنقل بينها، وfast-forward وthree-way merge، وتعارضات الدمج، وتنظيف الفروع، ومسارات الدمج العملية.

المراجع الرسمية ومواد إضافية للقراءة