DevOps والتشغيل الأدلة التقنية

Cherry-pick مع git bisect: نقل الإصلاح وإيجاد الخطأ

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

Cherry-pick مع git bisect: نقل الإصلاح وإيجاد الخطأ

إذا كنت تعمل على برنامج له عملاء، فسوف تمر بهذين الموقفين قريباً. الأول: عميل يعمل عنده الإصدار 1.0.0، ويكتشف خطأ في حساب مجموع الفاتورة، وأنت أصلحت الخطأ على main أمس، ولكن main فيه أيضاً ميزة أكواد الخصم التي لم تكتمل ولم تختبر، فلا تستطيع أن تعطيه main كما هو، ولا تريد أن تكتب الإصلاح مرة ثانية بيدك. والثاني: اختبار الخصم كان ينجح في الإصدار الأخير، واليوم يفشل، وبين الاثنين أحد عشر Commit من أشخاص مختلفين، ولا أحد يتذكر أنه لمس الخصم، فتبدأ بفتح كل Commit وقراءته واحداً بعد الآخر.

وفي Git أداتان صممتا لهذين الموقفين بالتحديد: الانتقاء Cherry-pick الذي ينسخ Commit واحداً من فرع إلى فرع، ومعه الوسوم Tags التي تعطي كل إصدار اسماً ثابتاً، والبحث الثنائي git bisect الذي يجد ال Commit الذي أدخل الخطأ بعدد قليل من الاختبارات، ويستطيع أن يشغل الاختبار بنفسه دون أن تلمس لوحة المفاتيح. وفي هذا المقال نجربهما خطوة بخطوة في Container صغير، وكل مخرج هو ما طبعه Git فعلاً، ومعه مشكلتان حقيقيتان وقعنا فيهما أثناء التجربة. وسوف نناقش في هذا المقال ما يلي:

  • تجهيز المختبر، وفرع الإصدار Release Branch: لماذا نحتاجه ومن أين يخرج.
  • الوسوم Tags: الفرق بين الخفيف والمشروح، ولماذا لا يدفعها git push.
  • الانتقاء git cherry-pick -x لنقل إصلاح إلى فرع الإصدار، ثم وسم الإصدار v1.0.1 وترقيم SemVer.
  • ماذا يحدث إذا انتقيت الإصلاح نفسه مرتين، وكيف تعرف بالأمر git cherry ما الذي نقلته.
  • التعارض عندما يعتمد الإصلاح على Commit لم تنقله، وانتقاء Merge Commit بالخيار -m.
  • البحث الثنائي git bisect يدوياً ثم تلقائياً بالأمر git bisect run، ورمز الخروج 125.
  • مشكلة حقيقية جعلت bisect يتهم Commit بريئاً، وكيف تكتب اختباراً لا يخدعك.
  • أخطاء شائعة، وجدول الموقف والأمر، وتدريب عملي.

تجهيز المختبر Lab Setup

نحتاج Git وPython فقط، والثاني لاختبار صغير يشغله bisect، وكلاهما في Container صغير من Alpine:

docker run -it --rm --name gsp-lab alpine:3.24 sh
apk add --no-cache git python3
git config --global user.name "ArabRoot Team"
git config --global user.email "[email protected]"
git config --global init.defaultBranch main

واستخدمنا Git 2.54.0 وPython 3.14 كما يأتيان مع Alpine 3.24. وأنشأنا مستودعاً مجرداً Bare Repository داخل ال Container يعمل كسيرفر، واستنسخناه إلى مجلد اسمه shop. وفيه ملف cart.py برقم الإصدار VERSION = "1.0.0" ودوال السعر والمجموع ووصف المنتج، وعلى أول Commit وضعنا الوسم v1.0.0 ودفعناه، وهذه هي النسخة التي يعمل بها العميل. وكل أوامر البناء موجودة في ملف المختبر مع المقال.

الوسوم Tags: اسم ثابت لكل إصدار

قبل الانتقاء نحتاج أن نفهم الوسم، لأن كل ما بعده يعتمد عليه. وقد رأينا في دليل المبتدئين أن الفرع اسم يتحرك مع كل Commit، أما الوسم فاسم يشير إلى Commit واحد ولا يتحرك أبداً، ولذلك نستخدمه لنقول «هذا بالضبط ما أعطيناه للعميل باسم 1.0.0»، فإذا جاءنا بعد سنة يقول إن عنده 1.0.0، نعرف أي كود يعمل عنده. وللوسم نوعان، أنشأنا من كل نوع واحداً على ال Commit نفسه:

git tag v1.0.0-light
git tag -n
git cat-file -t v1.0.0
git cat-file -t v1.0.0-light
git show --no-patch v1.0.0

والمخرج سوف يكون كما يلي:

v1.0.0          Release 1.0.0
v1.0.0-light    Release 1.0.0

tag

commit

tag v1.0.0
Tagger: ArabRoot Team <[email protected]>
Date:   Tue Nov 3 09:02:00 2026 +0300

Release 1.0.0

commit 2c58766c14b3d1b992461d6f36b8acbec72497f0
Author: ArabRoot Team <[email protected]>
Date:   Tue Nov 3 09:01:00 2026 +0300

    Release 1.0.0

في المخرج أعلاه لاحظ التالي:

  • الوسم v1.0.0 أنشأناه بالأمر git tag -a v1.0.0 -m "Release 1.0.0"، والخيار -a يعني Annotated أي مشروح. والوسم v1.0.0-light أنشأناه دون -a، فهو وسم خفيف Lightweight.
  • git tag -n يعرض الوسوم مع سطر من رسالتها، والخفيف ليس له رسالة، فيعرض رسالة ال Commit نفسه، ولهذا يبدوان متشابهين هنا.
  • الفرق الحقيقي يظهر في git cat-file -t الذي يطبع نوع الكائن: الوسم المشروح كائن مستقل من نوع tag، أما الخفيف فهو مجرد اسم يشير مباشرة إلى commit.
  • ولأن المشروح كائن كامل، فهو يحمل اسم من أنشأه Tagger ووقت الإنشاء ورسالة، كما يبين git show قبل أن يعرض ال Commit الذي يشير إليه.

ولهذا يقول توثيق git tag إن الوسوم المشروحة للإصدارات، والخفيفة للعلامات الخاصة أو المؤقتة. ويوجد سبب عملي أيضاً: الأمر git describe الذي سوف نستخدمه بعد قليل يعتمد على الوسوم المشروحة فقط افتراضياً، كما يذكر توثيقه. ثم حذفنا الوسم الخفيف لأننا لا نحتاجه:

git tag -d v1.0.0-light

والمخرج سوف يكون كما يلي:

Deleted tag 'v1.0.0-light' (was 2c58766)

فرع الإصدار Release Branch: لماذا نحتاجه؟

بعد الإصدار تابع الفريق العمل على main كالعادة، فأضاف أحدهم ميزة أكواد الخصم ولم يكملها، وفيها TODO واضح، ثم اكتشف آخر أن مجموع الفاتورة يحسب المنتجات التي كميتها صفر أو سالبة، فأصلحه:

git log --oneline

والمخرج سوف يكون كما يلي:

a8dc3da Ignore items with zero or negative quantity in total
82d32ea Add discount codes (unfinished)
2c58766 Release 1.0.0

والعميل يريد الإصلاح a8dc3da اليوم. ولو أعطيناه main لأخذ معه 82d32ea، أي ميزة لم تكتمل ولم يراجعها أحد، وهذا قد يكسر عنده ما كان يعمل. لذلك نحتاج مكاناً يمثل ما يعمل عند العميل، ونضيف إليه ما نختاره فقط، وهذا هو فرع الإصدار. ويخرج من الوسم نفسه، لأن الوسم هو بالضبط ما أعطيناه للعميل:

git switch -c release/1.0 v1.0.0

والمخرج سوف يكون كما يلي:

Switched to a new branch 'release/1.0'

الخيار -c ينشئ الفرع وينتقل إليه، والوسيط الأخير نقطة البداية، وهنا الوسم v1.0.0. واسم الفرع يحمل الرقمين الأولين فقط، لأن كل إصدارات 1.0.x من الإصلاحات سوف تخرج منه. وفي فرق كثيرة لا ينشئ الفريق فرع الإصدار إلا عند الحاجة، أي عندما يحتاج عميل إصلاحاً لإصدار قديم، وهذا ما يوصي به موقع Trunk-Based Development: فرع الإصدار يقطع من الفرع الرئيسي، ولا يدمج فيه أبداً، والإصلاحات تصله بالانتقاء.

كم إصداراً تدعم؟ Supported Versions

كل فرع إصدار تفتحه وعد للعميل بأنك سوف تنقل إليه الإصلاحات، وكل وعد له تكلفة: كل إصلاح على main يجب أن تسأل عنه هل ينقل إلى فرع 1.0، وفرع 1.1، وفرع 1.2، وكلما ابتعد الفرع عن main زادت فرصة التعارض كما سوف نرى. لذلك اتفق مع فريقك مبكراً على سياسة مكتوبة: كم إصداراً قديماً تدعم في الوقت نفسه، وإلى متى، وما نوع الإصلاحات التي تنقل إليها. والسياسة الشائعة في الفرق الصغيرة أن تدعم الإصدار الأخير والذي قبله فقط، وأن تنقل إلى الأقدم الإصلاحات الأمنية وحدها، وأن تعلن للعملاء موعد انتهاء الدعم لكل إصدار حتى لا يفاجؤوا. ومن دون هذه السياسة يتحول فريق صغير إلى فريق صيانة لخمسة إصدارات، وتصبح أداة الانتقاء أكثر أمر يستخدمه في يومه. وإذا كان برنامجك خدمة ويب تنشرها أنت للجميع، ولا يوجد عميل يملك نسخة خاصة، فغالباً لا تحتاج فروع إصدار أصلاً، فكل إصلاح يدخل main وينشر.

الانتقاء Cherry-pick: إصلاح واحد إلى فرع الإصدار

الأمر git cherry-pick يأخذ التغيير الذي أدخله Commit واحد، أي الفرق بينه وبين أبيه، ويطبقه على الفرع الذي تقف عليه، ثم ينشئ Commit جديداً بالرسالة نفسها. والاسم من جني الكرز، أي أن تختار حبة واحدة من الشجرة وتترك البقية. وننقل الإصلاح مع الخيار -x:

git cherry-pick -x main
git log --oneline
git show --no-patch --format=%B HEAD

والمخرج سوف يكون كما يلي:

Auto-merging cart.py
[release/1.0 d2b58b8] Ignore items with zero or negative quantity in total
 Date: Tue Nov 3 09:10:00 2026 +0300
 1 file changed, 1 insertion(+), 1 deletion(-)

d2b58b8 Ignore items with zero or negative quantity in total
2c58766 Release 1.0.0

Ignore items with zero or negative quantity in total

(cherry picked from commit a8dc3da663dfc2e14f46e1e0a6be384100d59e2a)

في المخرج أعلاه لاحظ التالي:

  • كتبنا main لأن آخر Commit فيه هو الإصلاح، وفي العمل اليومي سوف تكتب رقم ال Commit نفسه، مثل git cherry-pick -x a8dc3da، لأن الإصلاح غالباً لا يكون آخر شيء في main.
  • Auto-merging cart.py يعني أن Git طبق التغيير على نسخة الملف في فرع الإصدار، وهي مختلفة عن نسخة main، ونجح دون تعارض لأن السطر الذي يغيره الإصلاح موجود في الفرعين كما هو.
  • نشأ Commit جديد d2b58b8، برقم مختلف عن الأصل a8dc3da، لأن أباه مختلف. أي أن الانتقاء نسخ وليس نقلاً، والتغيير الآن موجود في المستودع مرتين.
  • تاريخ فرع الإصدار فيه Commitان فقط: الإصدار والإصلاح. وميزة الخصم 82d32ea لم تدخل.
  • الخيار -x أضاف إلى الرسالة سطر «cherry picked from commit» ومعه رقم الأصل الكامل.

ولماذا -x؟ لأنه بعد سنة، عندما ينظر أحد إلى فرع الإصدار ويرى هذا الإصلاح، يعرف من أين جاء، ويستطيع أن يفتح الأصل ويقرأ النقاش حوله. وينصح التوثيق باستخدامه عند الانتقاء بين فرعين عامين كما نفعل هنا، ولا ينصح به عند الانتقاء من فرعك الخاص لأن الرقم لن يفيد أحداً، ويذكر أيضاً أن السطر يضاف فقط عندما ينجح الانتقاء دون تعارض، فإذا حللت تعارضاً فأضفه إلى الرسالة بنفسك. ولنتأكد من النتيجة في الملف نفسه:

grep -n "def total" -A1 cart.py
grep -c discount cart.py

والمخرج سوف يكون كما يلي:

8:def total(items):
9-    return sum(price(i) for i in items if i["qty"] > 0)

0

دالة المجموع فيها الإصلاح، وكلمة discount لا تظهر في الملف أبداً، أي أن الميزة غير المكتملة بقيت في main. والصورة التالية تلخص ما حدث:

رسم لفرعين: main عليه A بوسم v1.0.0 ثم B لأكواد الخصم ثم F للإصلاح برقم a8dc3da، وفرع release/1.0 يخرج من A، وسهم متقطع ينسخ F إلى نسخة جديدة على فرع الإصدار برقم d2b58b8 ووسم v1.0.1، ثم سهم إلى سيرفر الإنتاج، وعلامة تبين أن B لم تدخل الإصدار، ومربع فيه رسالة ال Commit مع سطر cherry picked from commit
الانتقاء ينسخ Commit الإصلاح وحده إلى فرع الإصدار برقم جديد، وتبقى الميزة غير المكتملة في main

وقد تسأل: لماذا أصلحنا على main أولاً ثم نقلنا إلى فرع الإصدار، وليس العكس؟ الطريقتان موجودتان، فنموذج Git Flow يصلح في فرع hotfix ثم يدمجه في الفرعين، أما Trunk-Based Development فيوصي بالإصلاح على الفرع الرئيسي أولاً مع اختبار يثبته، ثم الانتقاء إلى فرع الإصدار. والسبب أن الإصلاح الذي يبدأ في فرع الإصدار قد ينسى ولا يصل إلى main، فيرجع الخطأ نفسه في الإصدار التالي، وهذا من أكثر الأخطاء إحراجاً أمام العميل.

وسم الإصدار Release Tag: من v1.0.1 إلى السيرفر

الآن نجهز الإصدار نفسه: نغير رقم الإصدار في الملف، ونضع وسماً مشروحاً، ونسأل Git أين نحن:

git commit -qam "Bump version to 1.0.1"
git tag -a v1.0.1 -m "Release 1.0.1: ignore zero or negative quantities"
git describe

والمخرج سوف يكون كما يلي:

v1.0.1

الأمر git describe يصف ال Commit الحالي بالنسبة لأقرب وسم مشروح قبله، وبما أننا على الوسم نفسه فقد طبع اسمه فقط. ولو أنشأنا Commit بعده لطبع شيئاً مثل v1.0.1-1-g ثم رقم ال Commit، أي Commit واحد بعد v1.0.1، وهذه صيغة مفيدة تضعها في رقم بناء البرنامج حتى تعرف من أي كود بني بالضبط. والآن ندفع الفرع، ثم ننظر إلى الوسوم على السيرفر:

git push -q -u origin release/1.0
git ls-remote --tags origin
git push origin v1.0.1
git ls-remote --tags origin

والمخرج سوف يكون كما يلي:

f6f3599b2ac7397394d69504559b316b9604ab10	refs/tags/v1.0.0
2c58766c14b3d1b992461d6f36b8acbec72497f0	refs/tags/v1.0.0^{}

To /work/remote.git
 * [new tag]         v1.0.1 -> v1.0.1

f6f3599b2ac7397394d69504559b316b9604ab10	refs/tags/v1.0.0
2c58766c14b3d1b992461d6f36b8acbec72497f0	refs/tags/v1.0.0^{}
2076fc6f2b3b954a625cd5a97548c045f1a826bd	refs/tags/v1.0.1
c9dccb1fdfbecad5cd61ae69408f8f56773f0d32	refs/tags/v1.0.1^{}

هذا خطأ يقع فيه كل من يضع أول وسم: دفعنا الفرع، والوسم على آخر Commit فيه، ومع ذلك فالأمر git ls-remote --tags الذي يسأل السيرفر عن وسومه لم يجد v1.0.1، لأن git push لا يدفع الوسوم أبداً إلا إذا طلبتها. فدفعناه باسمه، فظهر على السيرفر. ولكل وسم مشروح سطران: الأول رقم كائن الوسم نفسه، والثاني الذي ينتهي بالعلامة ^{} رقم ال Commit الذي يشير إليه، ولاحظ أن c9dccb1 هو Commit رفع الإصدار. وإذا أردت أن تدفع الوسوم المشروحة التي على ال Commits التي تدفعها في أمر واحد، فالخيار git push --follow-tags يفعل ذلك، وهو ما استخدمناه في بداية المختبر مع v1.0.0. والصورة التالية تجمع ما رأيناه عن الوسوم:

أربع لوحات: وسم خفيف v1.0.0-light يشير مباشرة إلى ال Commit وgit cat-file يطبع commit، ووسم مشروح v1.0.0 كائن فيه Tagger وتاريخ ورسالة ويطبع tag، وترقيم الإصدارات MAJOR.MINOR.PATCH مع إصلاح متوافق من 1.0.0 إلى 1.0.1 وميزة متوافقة إلى 1.1.0 وتغيير غير متوافق إلى 2.0.0، ومخرج git ls-remote قبل git push origin v1.0.1 وبعده
الوسم المشروح للإصدارات، والرقم يتبع SemVer، والوسم يدفع باسمه

ولماذا 1.0.1 وليس 1.1.0؟ لأن أغلب المشاريع تتبع ترقيم الإصدارات الدلالي Semantic Versioning 2.0.0 بالصيغة MAJOR.MINOR.PATCH: تزيد PATCH عند إصلاح متوافق مع ما قبله مثل إصلاحنا، وتزيد MINOR عند إضافة ميزة متوافقة مثل أكواد الخصم عندما تكتمل، وتزيد MAJOR عند تغيير غير متوافق في الواجهة العامة. فالعميل الذي يرى 1.0.1 يعرف أن الانتقال آمن ولا يحتاج أن يغير شيئاً عنده. وقد شرحنا ذلك بالتفصيل مع توليد سجل التغييرات من رسائل ال Commits في الإصدارات SemVer مع سجل التغييرات Changelog.

🛑
لا تقم بنقل وسم إصدار دفعته إلى Commit آخر، حتى لو اكتشفت خطأ بعد دقيقة من دفعه. فمن سحب الوسم القديم لن يحصل على الجديد تلقائياً، ويصبح للإصدار نفسه كودان مختلفان عند شخصين. والطريقة الصحيحة أن تصدر رقماً جديداً مثل v1.0.2.

نقل أكثر من Commit مرة واحدة Pick a Range

أحياناً يكون الإصلاح أكثر من Commit، مثل دالة لحساب ضريبة القيمة المضافة في ملف جديد ثم Commit يوثقها. والانتقاء يقبل مدى Range من ال Commits بالصيغة A..B، ومعناها كل ما بعد A حتى B، أي أن A نفسه لا يدخل، ولهذا نكتب main~2..main لنأخذ آخر Commitين:

git log --oneline -n 2 main
git cherry-pick -x main~2..main
git log --oneline -n 4

والمخرج سوف يكون كما يلي:

bccfba3 Document VAT rate
6edf02b Add VAT helper

[release/1.0 598d562] Add VAT helper
 Date: Tue Nov 3 10:14:00 2026 +0300
 1 file changed, 2 insertions(+)
 create mode 100644 vat.py
[release/1.0 a59464e] Document VAT rate
 Date: Tue Nov 3 10:15:00 2026 +0300
 1 file changed, 1 insertion(+)

a59464e Document VAT rate
598d562 Add VAT helper
c9dccb1 Bump version to 1.0.1
d2b58b8 Ignore items with zero or negative quantity in total

نقل Git ال Commitين بالترتيب من الأقدم إلى الأحدث، وكل واحد برقم جديد، فوق ما كان في فرع الإصدار. وإذا تعارض أحدهما توقف عنده كما في إعادة التأسيس، فتحل وتكمل بالأمر git cherry-pick --continue. ولأن هذه كانت تجربة، فقد أرجعنا الفرع كما كان بالأمر git reset --hard HEAD~2، فالضريبة ميزة وليست إصلاحاً، ومكانها الإصدار القادم 1.1.0.

ماذا لو انتقيت الإصلاح مرتين؟ What If

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

git cherry-pick main

والمخرج سوف يكون كما يلي:

Auto-merging cart.py
On branch release/1.0
The previous cherry-pick is now empty, possibly due to conflict resolution.
If you wish to commit it anyway, use:

    git commit --allow-empty

Otherwise, please use 'git cherry-pick --skip'
Your branch is up to date with 'origin/release/1.0'.

You are currently cherry-picking commit a8dc3da.
  (all conflicts fixed: run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

nothing to commit, working tree clean

Git طبق التغيير فلم يجد شيئاً يتغير، لأن الإصلاح موجود، فتوقف وأخبرك أن الانتقاء «فارغ» Empty، وأعطاك خيارين: أن تنشئ Commit فارغاً إذا كنت تريده لسبب ما، أو أن تتخطاه بالأمر --skip، وهذا ما فعلناه. والجميل أن Git لا يدخل التغيير مرتين، ولكنه لا يمنعك من محاولة النقل، فكيف تعرف قبل أن تحاول؟ الأمر git cherry يقارن فرعين ويخبرك أي Commits في الثاني ليس لها مقابل في الأول:

git cherry-pick --skip
git cherry -v release/1.0 main

والمخرج سوف يكون كما يلي:

+ 82d32eac20aaee0776b1c683af2051473bbf5c9e Add discount codes (unfinished)
- a8dc3da663dfc2e14f46e1e0a6be384100d59e2a Ignore items with zero or negative quantity in total

العلامة - أمام الإصلاح تعني أن له مقابلاً في release/1.0 يحمل التغيير نفسه، والعلامة + أمام ميزة الخصم تعني أنها غير موجودة هناك. والذكي في هذا الأمر أنه لا يقارن الأرقام، لأنها مختلفة أصلاً بعد الانتقاء، ولا الرسائل، وإنما يقارن التغيير نفسه، أي أنه يعرف أن d2b58b8 وa8dc3da إصلاح واحد. والخيار -v يضيف الرسالة. وهذا الأمر هو ما تحتاجه قبل كل إصدار إصلاحات: قائمة بما في main ولم يصل إلى فرع الإصدار، فتقرر لكل واحد هل ينقل أم لا.

عندما يعتمد الإصلاح على Commit لم تنقله Conflict

الانتقاء يطبق تغييرات Commit على حالة فرع آخر، فإذا كان التغيير يلمس كوداً غير موجود هناك فسوف يتوقف. وفي التجربة أضاف زميل إلى main إصلاحاً يقرب الأسعار والخصومات إلى منزلتين عشريتين، فغير سطر دالة السعر وسطراً في دالة الخصم، ثم حاولنا أن ننقله إلى فرع الإصدار:

git cherry-pick -x main
git status --short
git diff

والمخرج سوف يكون كما يلي، دون سطور النصائح hint:

Auto-merging cart.py
CONFLICT (content): Merge conflict in cart.py
error: could not apply 8107f73... Round prices and discounts to 2 decimals

UU cart.py

diff --cc cart.py
index 2b1a2d3,264e087..0000000
--- a/cart.py
+++ b/cart.py
@@@ -13,3 -13,8 +13,11 @@@ def describe(item)
      name = item["name"]
      qty = item["qty"]
      return f"{qty} x {name}"
++<<<<<<< HEAD
++=======
+
+
+ def discount(total, code):
+     # TODO: campaign codes, not finished
+     return round(total * 0.8, 2) if code == "LAUNCH" else total
++>>>>>>> 8107f73 (Round prices and discounts to 2 decimals)

هذا التعارض يستحق أن نقرأه بهدوء، لأنه يعلمك شيئاً عن الانتقاء:

  • جزء دالة السعر طبق دون مشكلة، ولهذا لا يظهر في git diff الذي يعرض ما تعارض فقط. والمشكلة في دالة الخصم: الإصلاح يغير سطراً فيها، ولكن الدالة كلها غير موجودة في فرع الإصدار.
  • الكتلة تحت HEAD فارغة، وهي فرع الإصدار، أي «لا يوجد شيء هنا»، والكتلة الثانية تريد أن تضيف دالة الخصم كاملة، لأن Git لا يستطيع أن يطبق تعديلاً على سطر دون أن يضع السطر نفسه.
  • git diff أثناء التعارض يعرض صيغة خاصة بعمودين من العلامات ++ و+ ، كل عمود يمثل طرفاً، وهذا يسمى Combined Diff.

ولو قبلنا الكتلة الثانية لدخلت ميزة الخصم غير المكتملة إلى الإصدار من الباب الخلفي، وهذا عكس ما نريده تماماً. وهنا القرار: إما أن نحل التعارض بأن نأخذ جزء دالة السعر فقط ونحذف دالة الخصم، وإما أن نلغي العملية ونطلب من صاحب الإصلاح أن يقسمه إلى Commitين، واحد للسعر وآخر للخصم، وهذا أنظف. فألغينا:

git cherry-pick --abort
git status --short

وgit status --short لم يطبع شيئاً، أي أن الفرع رجع كما كان قبل المحاولة. والدرس العملي: اجعل كل Commit إصلاح يحل شيئاً واحداً، ولا تخلط في Commit واحد إصلاحاً قد ينقل إلى إصدار قديم مع تعديل في ميزة جديدة. وإذا تكررت التعارضات عند الانتقاء إلى فرع إصدار، فهذه علامة على أن الفرع ابتعد كثيراً عن main، وأن الإصلاحات تعتمد على تغييرات لم تنقلها.

انتقاء Merge Commit: الخيار -m

وأحياناً لا يكون ما تريد نقله Commit واحداً، وإنما ميزة صغيرة كاملة دخلت main بMerge Commit. وفي التجربة دمجنا فرع نقاط الولاء في main بالخيار --no-ff، ثم طلب العميل الميزة في إصداره:

git cherry-pick main
git cherry-pick -m 1 -x main
git log --oneline -n 3
git show --stat --format=%B HEAD

والمخرج سوف يكون كما يلي:

error: commit 05f939dfb61ce16571f9c1afd8b8d00afc59e148 is a merge but no -m option was given.
fatal: cherry-pick failed

[release/1.0 42b2add] Merge branch 'feature/loyalty'
 Date: Tue Nov 3 09:35:00 2026 +0300
 1 file changed, 2 insertions(+)
 create mode 100644 loyalty.py

42b2add Merge branch 'feature/loyalty'
c9dccb1 Bump version to 1.0.1
d2b58b8 Ignore items with zero or negative quantity in total

Merge branch 'feature/loyalty'

(cherry picked from commit 05f939dfb61ce16571f9c1afd8b8d00afc59e148)


 loyalty.py | 2 ++
 1 file changed, 2 insertions(+)

رفض Git أولاً، والسبب نفسه الذي رأيناه مع revert في التراجع عن الأخطاء في Git: الانتقاء ينسخ «الفرق بين ال Commit وأبيه»، وMerge Commit له أبوان، فأي فرق تريد؟ والخيار -m 1 يقول الفرق عن الأب الأول، وهو main قبل الدمج، أي كل ما جاء من الفرع. فنشأ Commit عادي واحد على فرع الإصدار فيه ملف loyalty.py، والرسالة فيها سطر الأصل. ولاحظ أن النتيجة Commit عادي له أب واحد، وليس Merge Commit، فالانتقاء لا ينقل شكل التاريخ، وإنما التغيير فقط. ثم أرجعنا فرع الإصدار كما كان بالأمر git reset --hard HEAD~1، لأن هذه كانت تجربة وليست قراراً، فالإصدار 1.0.x للإصلاحات فقط. والصورة التالية تجمع النتائج الأربع التي رأيناها من الانتقاء:

أربع لوحات: نسخة نظيفة مع -x وفيها سطر cherry picked from commit، والإصلاح موجود من قبل فالانتقاء فارغ وgit cherry يضع علامة ناقص أمامه، وإصلاح يعتمد على Commit لم تنقله فيظهر تعارض ثم git cherry-pick --abort، وMerge Commit يرفض دون -m ثم ينجح مع -m 1
نسخة نظيفة، أو انتقاء فارغ، أو تعارض بسبب اعتماد على Commit آخر، أو رفض Merge Commit دون -m

وقاعدة الأمان في الانتقاء أنه لا يغير أي Commit موجود، فهو يضيف فقط، لذلك فهو آمن على أي فرع بما فيه الفروع المشتركة. ولكن لا تقم باستخدامه بديلاً عن الدمج لنقل ميزات كاملة بين فرعين يعيشان طويلاً، لأن كل Commit سوف يظهر مرتين برقمين مختلفين، وعند الدمج بينهما لاحقاً قد تظهر تعارضات على تغييرات موجودة في الطرفين أصلاً. والانتقاء مناسب لشيء واحد بالتحديد: إصلاح قليل منفرد يصل إلى مكان لا تريد أن يصله غيره.

روتين إصدار الإصلاحات Patch Release Routine

بعد كل ما جربناه، هذه هي الخطوات التي ننصح أن يتبعها الفريق كلما احتاج عميل إصلاحاً في إصدار قديم، وكل خطوة رأيناها في المختبر:

ست بطاقات مرقمة: أصلح على main أولاً مع اختبار برقم a8dc3da، ثم اعرف ما ينقص الإصدار بالأمر git cherry -v، ثم انتق الإصلاح وحده بالأمر git cherry-pick -x فيصبح d2b58b8، ثم ارفع الرقم وضع وسماً git tag -a v1.0.1، ثم ادفع الفرع والوسم، ثم CI يبني من الوسم وينشر عند العميل
إصلاح على main، ثم انتقاء، ثم وسم، ثم دفع، وCI يبني الإصدار من الوسم

والخطوة الأخيرة تستحق كلمة: أغلب الفرق لا تبني الإصدار من جهاز أحد، وإنما تجعل خط CI يبدأ عندما يصل وسم جديد إلى السيرفر، فيبني البرنامج من ال Commit الذي يشير إليه الوسم، ويختبره، وينشره. وبهذا يصبح الوسم نفسه هو قرار الإصدار، ولا يمكن أن يختلف ما بني عما وسم. وقد شرحنا تشغيل خطوط CI على سيرفرك في Gitea Actions. ولاحظ أن الأمر git push origin release/1.0 v1.0.1 يدفع الفرع والوسم معاً في سطر واحد، لأن git push يقبل أكثر من اسم.

البحث الثنائي git bisect: أي Commit أدخل الخطأ؟

ننتقل الآن إلى الموقف الثاني. في مستودع آخر، الخصم يجب أن يكون 10%، فالخصم على 100 يعطي 90، ومعه اختبار صغير يتأكد من ذلك، وكان ينجح عند الوسم v1.0.0. واليوم يفشل. هذا هو الاختبار test_discount.py:

import sys
try:
    from cart import discount
except Exception as e:          # the code does not even import: cannot test this commit
    print("SKIP:", type(e).__name__)
    sys.exit(125)
got = discount(100)
if got != 90.0:
    print("FAIL: discount(100) =", got)
    sys.exit(1)
print("OK")

الاختبار بسيط عن قصد: يستورد الدالة، فإذا لم يستطع حتى أن يستوردها لأن الكود فيه خطأ في الصياغة يطبع SKIP ويخرج بالرمز 125، وسوف نشرح هذا الرقم بعد قليل. ثم يحسب الخصم، فإذا لم يكن 90 يطبع FAIL ويخرج بالرمز 1، وإلا يطبع OK ويخرج بالصفر. وهذا هو التاريخ والاختبار الآن:

git log --oneline
python3 test_discount.py

والمخرج سوف يكون كما يلي:

28c238a Docs: note 7
37e56a3 Docs: note 6
5f2b4d0 Docs: note 5
8a39d26 Docs: note 4
b68e11e Tune discount for campaign
76f8cf6 Fix syntax in discount
68ce462 Refactor discount signature
efc64ac Add shipping fee
3efa3b8 Docs: note 3
4d7ed67 Docs: note 2
7769a7f Docs: note 1
2322fa3 Add discount with test

FAIL: discount(100) = 80.0

أحد عشر Commit بعد الإصدار، والخصم الآن 20%. وفي هذا المثال الصغير قد تخمن الجواب من الرسائل، ولكن في الحياة الحقيقية الرسائل لا تساعد بهذا الشكل، والتاريخ فيه مئات ال Commits، والخطأ قد يأتي من مكان لا تتوقعه. والطريقة البسيطة أن ترجع إلى كل Commit وتختبره، أي أحد عشر اختباراً هنا، وألف اختبار في مشروع كبير. أما git bisect فيستخدم البحث الثنائي Binary Search: تعطيه Commit سليماً Good وآخر معطوباً Bad، فيختار ال Commit الذي في المنتصف، وتختبره، وبحسب النتيجة يستبعد النصف الذي لا يمكن أن يكون فيه الخطأ، ثم يكرر. ومع كل خطوة ينقسم العدد على اثنين، فألف Commit تحتاج نحو عشر خطوات فقط، لأن 2 أس 10 يساوي 1024.

البحث يدوياً خطوة بخطوة Manual Bisect

نبدأ يدوياً حتى نفهم ما يحدث، ثم نجعله تلقائياً. نخبر Git بنقطتي البداية:

git bisect start
git bisect bad
git bisect good v1.0.0

والمخرج سوف يكون كما يلي:

status: waiting for both good and bad commits

status: waiting for good commit(s), bad commit known

Bisecting: 5 revisions left to test after this (roughly 3 steps)
[68ce462b2e8f3ba9211c73c9171dd6762410d1e2] Refactor discount signature

الأمر start يبدأ الجلسة، وbad دون رقم تعني أن ال Commit الحالي معطوب، وgood v1.0.0 تعني أن الوسم سليم. وبمجرد أن عرف الطرفين، اختار Git ال Commit الذي في المنتصف 68ce462 وانتقل إليه، وأخبرنا أن بعد هذا الاختبار بقي نحو 5 Commits و3 خطوات تقريباً. ومن أين جاء الرقم 3؟ بين الوسم السليم وHEAD المعطوب أحد عشر Commit يمكن أن يكون أي منها هو المتهم، وكل اختبار يقسم هذا العدد على اثنين تقريباً، فبعد الاختبار الأول يبقى نحو خمسة، ثم اثنان، ثم واحد، أي ثلاث خطوات بعد هذه. وهذا ما يجعل البحث الثنائي مفيداً في المشاريع الكبيرة تحديداً: لو كان بين الإصدارين ألفا Commit، فإن الطريقة البسيطة تحتاج حتى ألفي اختبار، أما bisect فيحتاج نحو إحدى عشرة خطوة. والفرق يكبر كلما كان الاختبار نفسه بطيئاً، مثل بناء كامل يستغرق دقائق. والآن نختبر، ونطبع رمز الخروج حتى نراه:

python3 -B test_discount.py; echo "exit code: $?"
git bisect skip
python3 -B test_discount.py; echo "exit code: $?"
git bisect good

والمخرج سوف يكون كما يلي:

SKIP: SyntaxError
exit code: 125

Bisecting: 5 revisions left to test after this (roughly 3 steps)
[76f8cf6459845686b6dbf53856d9babf4e7deb5a] Fix syntax in discount

OK
exit code: 0

Bisecting: 1 revision left to test after this (roughly 1 step)
[5f2b4d0834e9727a5bf54b4d53354a1ed1a0fef3] Docs: note 5

في المخرج أعلاه لاحظ التالي:

  • ال Commit الأول الذي اختاره لا يمكن اختباره أصلاً، فأحدهم أعاد ترتيب الدالة ونسي النقطتين في سطر التعريف، فالكود لا يستورد. وهذا ليس «سليماً» ولا «معطوباً» بالنسبة للخطأ الذي نبحث عنه، لذلك قلنا لGit skip أي تخطه، فاختار Commit مجاوراً.
  • ال Commit التالي 76f8cf6 أصلح الصياغة، والاختبار نجح، فقلنا good. وبهذا استبعد Git كل ما قبله، وبقي Commit واحد تقريباً بين السليم والمعطوب.
  • والخيار -B في Python له قصة، فهو ليس هنا للزينة، وسوف نشرحه في القسم التالي لأنه كلفنا محاولة كاملة.

ونستطيع أن نكمل هكذا حتى النهاية، ولكننا نعرف الآن الفكرة، فننهي الجلسة بالأمر git bisect reset، الذي يرجعك إلى الفرع الذي كنت فيه، وننتقل إلى الطريقة التلقائية.

git bisect reset

والمخرج سوف يكون كما يلي:

Previous HEAD position was 5f2b4d0 Docs: note 5
Switched to branch 'main'

البحث التلقائي git bisect run

بدلاً من أن تشغل الاختبار وتكتب good أو bad بنفسك، تعطي Git الأمر الذي يختبر، فيشغله على كل Commit يختاره، ويقرأ رمز الخروج Exit Code ليعرف النتيجة. وقواعد الرموز في التوثيق واضحة: الصفر يعني سليم، وأي رقم من 1 إلى 127 ما عدا 125 يعني معطوب، والرقم 125 يعني لا يمكن اختبار هذا ال Commit فتخطه. ولماذا 125 بالذات؟ يقول التوثيق إنه أعلى رقم مناسب لهذا الغرض، لأن 126 و127 تستخدمهما الصدفة Shell لأخطاء خاصة، مثل أمر غير موجود، ولو استخدمهما اختبارك لاختلط عليك هل فشل الاختبار أم فشل تشغيله. ولهذا كتبنا اختبارنا بحيث يخرج بالرمز 125 عندما لا يستطيع أن يستورد الكود. والأمر نفسه يحدد الطرفين في سطر واحد:

git bisect start HEAD v1.0.0
git bisect run python3 -B test_discount.py

والمخرج سوف يكون كما يلي:

Bisecting: 5 revisions left to test after this (roughly 3 steps)
[68ce462b2e8f3ba9211c73c9171dd6762410d1e2] Refactor discount signature

running 'python3' '-B' 'test_discount.py'
SKIP: SyntaxError
Bisecting: 5 revisions left to test after this (roughly 3 steps)
[76f8cf6459845686b6dbf53856d9babf4e7deb5a] Fix syntax in discount
running 'python3' '-B' 'test_discount.py'
OK
Bisecting: 1 revision left to test after this (roughly 1 step)
[5f2b4d0834e9727a5bf54b4d53354a1ed1a0fef3] Docs: note 5
running 'python3' '-B' 'test_discount.py'
FAIL: discount(100) = 80.0
Bisecting: 0 revisions left to test after this (roughly 1 step)
[8a39d2649c871e6cbb412a1164f3569a4d89bf3f] Docs: note 4
running 'python3' '-B' 'test_discount.py'
FAIL: discount(100) = 80.0
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[b68e11eacf2b828f39f842ab7593d98d446366a0] Tune discount for campaign
running 'python3' '-B' 'test_discount.py'
FAIL: discount(100) = 80.0
b68e11eacf2b828f39f842ab7593d98d446366a0 is the first bad commit
commit b68e11eacf2b828f39f842ab7593d98d446366a0
Author: ArabRoot Team <[email protected]>
Date:   Tue Nov 3 09:49:00 2026 +0300

    Tune discount for campaign

 cart.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
bisect found first bad commit

في المخرج أعلاه لاحظ التالي:

  • كل سطر running خطوة واحدة شغل فيها Git الاختبار، وتحته ما طبعه الاختبار، ثم ال Commit التالي الذي اختاره بحسب النتيجة.
  • من أحد عشر Commit اختبر Git خمسة فقط، وأحدها تخطاه، ولو لم يكن هناك Commit معطوب الصياغة لكانت الخطوات أقل.
  • النتيجة «Tune discount for campaign» الذي غير الخصم إلى 20%، وطبع Git معلوماته وإحصائية التغيير: سطر واحد في cart.py. ولاحظ أن رسالته لا توحي أنه يعطل شيئاً، وهذا هو الوضع الطبيعي في الحياة الحقيقية، فلا أحد يكتب «Break discount».

والصورة التالية تبين البحث كله على خط ال Commits، بالأرقام الحقيقية، وترتيب الخطوات الخمس:

خط من اثني عشر Commit من v1.0.0 السليم إلى HEAD المعطوب، وعليه خمس خطوات مرقمة: 1 على Refactor باللون الأصفر لأنه تخطى، و2 على Fix syntax بالأخضر لأنه سليم، و3 و4 و5 على Docs 5 وDocs 4 وTune بالأحمر، وTune محاط بحلقة لأنه أول Commit معطوب، وتحت الخط جدول بنتيجة كل خطوة ورمز خروجها
خمس خطوات بدلاً من أحد عشر اختباراً، وكل خطوة تستبعد نصف ما بقي

وبعد أن تجد ال Commit، لا تنس أن تنهي الجلسة بالأمر git bisect reset، وإلا بقيت على Commit قديم دون فرع. ويحفظ Git سجل الجلسة كاملاً، وتستطيع أن تراه قبل reset:

git bisect log

والمخرج سوف يكون كما يلي:

# bad: [28c238ac8de1420c1a13d700b9cdb99b8ac8ace1] Docs: note 7
# good: [2322fa33dd9795702e7f4ed6a1c5b74c8e84ffa0] Add discount with test
git bisect start 'HEAD' 'v1.0.0'
# skip: [68ce462b2e8f3ba9211c73c9171dd6762410d1e2] Refactor discount signature
git bisect skip 68ce462b2e8f3ba9211c73c9171dd6762410d1e2
# good: [76f8cf6459845686b6dbf53856d9babf4e7deb5a] Fix syntax in discount
git bisect good 76f8cf6459845686b6dbf53856d9babf4e7deb5a
# bad: [5f2b4d0834e9727a5bf54b4d53354a1ed1a0fef3] Docs: note 5
git bisect bad 5f2b4d0834e9727a5bf54b4d53354a1ed1a0fef3
# bad: [8a39d2649c871e6cbb412a1164f3569a4d89bf3f] Docs: note 4
git bisect bad 8a39d2649c871e6cbb412a1164f3569a4d89bf3f
# bad: [b68e11eacf2b828f39f842ab7593d98d446366a0] Tune discount for campaign
git bisect bad b68e11eacf2b828f39f842ab7593d98d446366a0
# first bad commit: [b68e11eacf2b828f39f842ab7593d98d446366a0] Tune discount for campaign

السجل نفسه سكربت: الأسطر التي لا تبدأ بالعلامة # أوامر Git، فإذا أخطأت في خطوة يدوية تستطيع أن تحفظ السجل في ملف، وتحذف الخطوة الخاطئة، ثم تعيد تشغيله بالأمر git bisect replay. وهو أيضاً ما تضعه في تذكرة الخطأ Issue حتى يعرف زملاؤك كيف وصلت إلى النتيجة.

عندما اتهم bisect Commit بريئاً: مشكلة Stale Cache

ما عرضناه أعلاه هو المحاولة الثانية. أما المحاولة الأولى، دون الخيار -B، فقد أعطت نتيجة خاطئة تماماً، ونعرضها كما حدثت لأنها أهم درس في هذا المقال:

git bisect start HEAD v1.0.0
git bisect run python3 test_discount.py

والمخرج سوف يكون كما يلي، دون السطرين الأولين اللذين رأيناهما في المحاولة الصحيحة:

running 'python3' 'test_discount.py'
SKIP: SyntaxError
Bisecting: 5 revisions left to test after this (roughly 3 steps)
[76f8cf6459845686b6dbf53856d9babf4e7deb5a] Fix syntax in discount
running 'python3' 'test_discount.py'
OK
Bisecting: 1 revision left to test after this (roughly 1 step)
[5f2b4d0834e9727a5bf54b4d53354a1ed1a0fef3] Docs: note 5
running 'python3' 'test_discount.py'
OK
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[37e56a30673378230055dc6124a85165cdefc4bc] Docs: note 6
running 'python3' 'test_discount.py'
OK
28c238ac8de1420c1a13d700b9cdb99b8ac8ace1 is the first bad commit
commit 28c238ac8de1420c1a13d700b9cdb99b8ac8ace1
Author: ArabRoot Team <[email protected]>
Date:   Tue Nov 3 09:53:00 2026 +0300

    Docs: note 7

 README.md | 1 +
 1 file changed, 1 insertion(+)
bisect found first bad commit

Git يتهم «Docs: note 7»، وهو Commit يضيف سطراً إلى README فقط، ولا يمكن أن يغير نتيجة دالة في cart.py. والأغرب أن «Docs: note 5» نجح، مع أنه بعد Commit تغيير الخصم، أي أن الخصم فيه 20%. فالاختبار نفسه كذب. وهذه أول علامة يجب أن تنتبه لها دائماً: إذا اتهم bisect Commit لا يلمس الكود الذي تختبره، فالمشكلة في الاختبار وليس في التاريخ. بحثنا عن السبب:

git bisect reset
git status --short --ignored
ls __pycache__

والمخرج سوف يكون كما يلي:

Previous HEAD position was 37e56a3 Docs: note 6
Switched to branch 'main'

?? __pycache__/

cart.cpython-314.pyc

وجدنا مجلد __pycache__ وفيه cart.cpython-314.pyc، وهو نسخة مترجمة Bytecode من cart.py يحفظها Python حتى لا يترجم الملف في كل مرة. وكيف يعرف Python أن النسخة المحفوظة قديمة؟ الطريقة الافتراضية، كما في PEP 552، أن يحفظ داخل الملف المترجم وقت آخر تعديل للمصدر وحجمه، فإذا تطابقا استخدم النسخة المحفوظة. وفي تجربتنا تحقق الشرطان بالصدفة: السطران RATE = 0.10 وRATE = 0.20 بالطول نفسه، وكان bisect ينتقل بين ال Commits بسرعة فكتب الملف في الثانية نفسها، فاستخدم Python في كل خطوة الكود المترجم من أول تشغيل، وهو الكود السليم. ولهذا نجحت كل الاختبارات حتى آخر Commit، فاتهم Git آخر Commit.

والحل خطوتان: حذفنا المجلد __pycache__، ثم شغلنا Python بالخيار -B الذي يمنعه من كتابة هذه الملفات أصلاً، كما في توثيق سطر الأوامر، فأصبح كل اختبار يقرأ cart.py الحالي، ووصلنا إلى النتيجة الصحيحة. وهذه المشكلة ليست خاصة بPython، فأي أداة بناء تحفظ نتائج سابقة، مثل مجلد بناء أو Cache لأداة تجميع، قد تجعل bisect يختبر كوداً غير الكود الذي في ال Commit. والصورة التالية تلخص المحاولتين والقواعد التي خرجنا بها:

لوحتان: المحاولة الأولى بالأمر git bisect run python3 test_discount.py تجد Docs: note 5 وDocs: note 6 سليمين وتتهم Docs: note 7 مع علامة تحذير وملف __pycache__/cart.cpython-314.pyc، وبعد الإصلاح بحذف __pycache__ واستخدام python3 -B تجد Tune discount for campaign، وتحتها أربع قواعد لكل أمر تعطيه لـ bisect run
المحاولة الأولى اختبرت كوداً مترجماً قديماً، والثانية بدأت كل خطوة من حالة نظيفة

ومن هذه التجربة خرجنا بقواعد لأي أمر تعطيه لـ git bisect run:

  • اختبر الأمر على الطرفين قبل البدء: شغله على HEAD وتأكد أنه يفشل، وعلى الوسم السليم وتأكد أنه ينجح. ولو فعلنا ذلك في المحاولة الأولى لما اكتشفنا المشكلة، لأن الطرفين كانا صحيحين، ولكنها تكشف أغلب الأخطاء الأخرى.
  • ابدأ كل خطوة من حالة نظيفة: لا ملفات بناء قديمة ولا Cache، وإذا كان المشروع يحتاج بناء فاجعل الأمر سكربتاً يبني من الصفر ثم يختبر.
  • استخدم الرمز 125 لما لا يمكن اختباره: مثل كود لا يبنى أو اعتماديات لا تثبت، حتى لا يحسب «معطوباً» بسبب لا علاقة له بالخطأ.
  • شك في النتيجة إذا كانت لا تلمس الكود: افتح ال Commit المتهم بالأمر git show، فإذا كان لا يغير شيئاً يتعلق بالخطأ فأعد البحث.
  • أضف __pycache__/ إلى .gitignore: ظهر في git status كملف جديد، وهذا وحده كان يجب أن ينبهنا.

البحث عن تغيير وليس عن خطأ: --term-old مع --term-new

الكلمتان good وbad توحيان بأن bisect يبحث عن أخطاء فقط، ولكنه في الحقيقة يبحث عن أول Commit تغير عنده أي شيء تستطيع أن تفحصه: متى أصبح البرنامج أسرع، أو متى ظهرت رسالة معينة، أو متى تغير إعداد. ولكي لا تحتار في أيهما «سليم»، يسمح لك Git أن تسمي الحالتين بنفسك. وهنا سؤالنا: متى أصبح الخصم 20%؟ فسمينا الحالة القديمة before والجديدة after، والأمر يخرج بالصفر، أي before، ما دام السطر RATE = 0.20 غير موجود:

git bisect start --term-old=before --term-new=after HEAD v1.0.0
git bisect run sh -c "! grep -q \"RATE = 0.20\" cart.py"

والمخرج سوف يكون كما يلي:

Bisecting: 5 revisions left to test after this (roughly 3 steps)
[68ce462b2e8f3ba9211c73c9171dd6762410d1e2] Refactor discount signature

running 'sh' '-c' ''\!' grep -q "RATE = 0.20" cart.py'
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[8a39d2649c871e6cbb412a1164f3569a4d89bf3f] Docs: note 4
running 'sh' '-c' ''\!' grep -q "RATE = 0.20" cart.py'
Bisecting: 0 revisions left to test after this (roughly 1 step)
[b68e11eacf2b828f39f842ab7593d98d446366a0] Tune discount for campaign
running 'sh' '-c' ''\!' grep -q "RATE = 0.20" cart.py'
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[76f8cf6459845686b6dbf53856d9babf4e7deb5a] Fix syntax in discount
running 'sh' '-c' ''\!' grep -q "RATE = 0.20" cart.py'
b68e11eacf2b828f39f842ab7593d98d446366a0 is the first after commit
commit b68e11eacf2b828f39f842ab7593d98d446366a0
Author: ArabRoot Team <[email protected]>
Date:   Tue Nov 3 09:49:00 2026 +0300

    Tune discount for campaign

 cart.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
bisect found first bad commit

في المخرج أعلاه لاحظ التالي:

  • العلامة ! في أول الأمر تعكس نتيجة grep، فإذا وجد السطر خرج بالرقم 1 أي after، وإذا لم يجده خرج بالصفر أي before. وطريقة Git في طباعة الأمر تبدو غريبة، ولكنها فقط طريقته في وضع العلامة بين علامات تنصيص.
  • هذه المرة لم يحتج Git أن يتخطى «Refactor discount signature»، لأن grep لا يهتم أن الكود لا يستورد، فهو يقرأ النص فقط. فاختيار الأمر الذي يفحص يغير عدد الخطوات ونتيجة كل خطوة.
  • النتيجة في السطر is the first after commit بالاسم الذي اخترناه، أما السطر الأخير فما زال يقول first bad commit، وهذا ما طبعه الإصدار الذي جربناه كما هو.

نصائح أخرى مع bisect Tips

البحث الثنائي يعمل على أي تاريخ، ولكنه أسهل وأسرع عندما يكون كل Commit في main يبنى وتنجح اختباراته، لأن كل Commit لا يبنى يصبح خطوة ضائعة يتخطاها Git. وهذه واحدة من فوائد التاريخ النظيف الذي شرحناه في Merge أم Rebase أم Squash، فCommits «WIP» التي لا تعمل تجعل bisect أصعب. وإذا كان الخطأ ليس اختباراً يفشل وإنما سلوكاً تراه بعينك، فاستخدم الطريقة اليدوية، وشغل البرنامج في كل خطوة، وقل good أو bad. وإذا كنت لا تريد أن يغير bisect مجلد عملك وفيه تعديلات، فافتح مجلد عمل مستقلاً بالأمر git worktree كما شرحنا في التبديل بين المهام في Git، وابحث هناك، فحالة bisect خاصة بكل مجلد عمل.

أخطاء شائعة Common Mistakes

  • الإصلاح في فرع الإصدار فقط: لا يصل إلى main، فيرجع الخطأ في الإصدار التالي. أصلح على main أولاً ثم انتق.
  • Commit إصلاح يخلط أكثر من شيء: يتعارض عند الانتقاء أو يدخل معه كوداً لا تريده، كما رأينا مع التقريب والخصم.
  • نسيان دفع الوسم: git push لا يدفعه، فادفعه باسمه أو استخدم --follow-tags، وتحقق بالأمر git ls-remote --tags.
  • وسم خفيف لإصدار: لا يحمل من أنشأه ولا متى، وgit describe يتجاهله افتراضياً.
  • نقل وسم منشور: أصدر رقماً جديداً بدلاً من ذلك.
  • الانتقاء بديلاً عن الدمج بين فرعين طويلين: كل تغيير يظهر مرتين، والدمج لاحقاً يتعارض.
  • الوثوق بنتيجة bisect دون فحص: رأينا اتهاماً لCommit يغير README فقط بسبب Cache قديم.
  • نسيان git bisect reset: تبقى على Commit قديم دون فرع، ثم تلتزم عليه وتظن أنك في main.

الموقف والأمر Cheat Sheet

الموقفالأمر
وسم إصدار مشروحgit tag -a v1.0.1 -m "..."
دفع وسمgit push origin v1.0.1 أو git push --follow-tags
رؤية الوسوم على السيرفرgit ls-remote --tags origin
وصف ال Commit الحالي بالنسبة لآخر إصدارgit describe
فرع إصدار من وسمgit switch -c release/1.0 v1.0.0
نسخ إصلاح إلى فرع الإصدارgit cherry-pick -x <hash>
ما في main ولم يصل إلى فرع الإصدارgit cherry -v release/1.0 main
انتقاء فارغ لأن التغيير موجودgit cherry-pick --skip
إلغاء انتقاء متعارضgit cherry-pick --abort
نسخ ما جاء به Merge Commitgit cherry-pick -m 1 -x <hash>
بدء البحث الثنائيgit bisect start HEAD v1.0.0
البحث التلقائي باختبارgit bisect run <command>، والرمز 125 للتخطي
تخطي Commit لا يمكن اختباره يدوياًgit bisect skip
سجل الجلسة وإعادتهاgit bisect log وgit bisect replay <file>
إنهاء الجلسة والرجوع إلى الفرعgit bisect reset

تدريب عملي Practice

  1. أنشئ مستودعاً بوسم v1.0.0، ثم أضف على main ميزة غير مكتملة وإصلاحاً منفصلاً، وأنشئ فرع إصدار من الوسم، وانقل الإصلاح وحده بالأمر git cherry-pick -x، ثم تحقق بالأمر git cherry -v.
  2. ضع وسماً مشروحاً v1.0.1، وادفع الفرع، وتحقق بالأمر git ls-remote --tags أن الوسم لم يصل، ثم ادفعه.
  3. اكتب إصلاحاً يغير دالة غير موجودة في فرع الإصدار، وحاول أن تنقله، واقرأ التعارض، ثم ألغه بالأمر --abort.
  4. أنشئ عشرين Commit، واجعل واحداً منها يعطل اختباراً، وآخر لا يستورد، ثم ابحث بالأمر git bisect run مع رمز الخروج 125، وعد الخطوات.
  5. أعد التجربة دون حذف __pycache__ ودون -B، وانظر هل تتكرر النتيجة الخاطئة عندك.

ماذا تقرأ بعد ذلك؟ Next Steps

دليلالإصدارات SemVer مع سجل التغييرات Changelogكيف تعطي كل إصدار رقماً يعرف منه من يستخدم الكود هل الانتقال آمن، وتولد سجل التغييرات من رسائل Commits دون أن يضيع تغيير مهم.دليلMerge أم Rebase أم Squash؟ دمج الفروع في Git خطوة بخطوةثلاث طرق لإدخال عمل فرعك إلى main، نجربها على المستودع نفسه حتى ترى بعينك ماذا تفعل كل واحدة بالتاريخ، ومتى تختارها، وكيف تحل التعارض في كل منها.دليلالتراجع عن الأخطاء في Git: revert أم reset أم restore؟لكل خطأ في Git أمر تراجع يناسب المكان الذي وصل إليه، وهنا تتعلم أن تختاره بسؤال واحد، وأن تسترجع عملاً ظننت أنه ضاع.دليلTrunk-Based Development: فروع قصيرة ودمج يوميلماذا تنفجر الفروع الطويلة يوم الإصدار، وكيف يدمج الفريق عمله في main كل يوم بأمان مع CI وFeature Flags.

إذا وجدت ال Commit المعطوب وتريد أن تعكسه على main دون أن تمسح التاريخ، فاقرأ التراجع عن الأخطاء في Git. وإذا كان فريقك يدير أكثر من إصدار في الوقت نفسه فاقرأ التطوير على الفرع الرئيسي Trunk-Based، حيث تقطع فروع الإصدار عند الحاجة وتصلها الإصلاحات بالانتقاء. والخريطة الكاملة لهذه المقالات في Git في العمل اليومي.

الخلاصة Summary

  • الوسم اسم ثابت لCommit، والمشروح منه كائن بكاتب وتاريخ ورسالة، وهو الذي تستخدمه للإصدارات، وgit push لا يدفعه إلا باسمه أو مع --follow-tags.
  • فرع الإصدار يخرج من وسم الإصدار، ولا يدمج في main، والإصلاحات تصله بالانتقاء بعد أن تدخل main أولاً.
  • git cherry-pick -x ينسخ تغيير Commit واحد برقم جديد ويكتب أصله في الرسالة، وgit cherry يخبرك بما نقلته وما لم تنقله.
  • كل فرع إصدار تفتحه وعد بالصيانة، فاكتب سياسة واضحة لعدد الإصدارات التي تدعمها ومدة دعمها، وانقل إلى الأقدم الإصلاحات الأمنية فقط.
  • الانتقاء الفارغ يعني أن التغيير موجود، والتعارض غالباً يعني أن الإصلاح يعتمد على شيء لم تنقله، وMerge Commit يحتاج -m 1.
  • git bisect يجد أول Commit معطوب بعدد خطوات يقارب لوغاريتم عدد ال Commits، وgit bisect run يشغل الاختبار بنفسه، والرمز 125 للتخطي.
  • الاختبار الذي تعطيه لـ bisect يجب أن يرى الكود الحالي فعلاً، فابدأ كل خطوة من حالة نظيفة، وشك في أي نتيجة تشير إلى Commit لا يلمس الكود.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة المقال، وتنفيذ كل الأمثلة على git 2.54.0 وPython 3.14 داخل Container من alpine:3.24، مع مستودع Bare محلي لدفع الفرع والوسوم. ويأخذ المقال أقسام الانتقاء والوسوم والبحث الثنائي من دليل Git في العمل اليومي بعد تقسيمه إلى أربعة مقالات.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.