إذا كنت تعمل على برنامج له عملاء، فسوف تمر بهذين الموقفين قريباً. الأول: عميل يعمل عنده الإصدار 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 أولاً ثم نقلنا إلى فرع الإصدار، وليس العكس؟ الطريقتان موجودتان، فنموذج 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. والصورة التالية تجمع ما رأيناه عن الوسوم:

ولماذا 1.0.1 وليس 1.1.0؟ لأن أغلب المشاريع تتبع ترقيم الإصدارات الدلالي Semantic Versioning 2.0.0 بالصيغة MAJOR.MINOR.PATCH: تزيد PATCH عند إصلاح متوافق مع ما قبله مثل إصلاحنا، وتزيد MINOR عند إضافة ميزة متوافقة مثل أكواد الخصم عندما تكتمل، وتزيد MAJOR عند تغيير غير متوافق في الواجهة العامة. فالعميل الذي يرى 1.0.1 يعرف أن الانتقال آمن ولا يحتاج أن يغير شيئاً عنده. وقد شرحنا ذلك بالتفصيل مع توليد سجل التغييرات من رسائل ال Commits في الإصدارات SemVer مع سجل التغييرات Changelog.
نقل أكثر من 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 cleanGit طبق التغيير فلم يجد شيئاً يتغير، لأن الإصلاح موجود، فتوقف وأخبرك أن الانتقاء «فارغ» 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 للإصلاحات فقط. والصورة التالية تجمع النتائج الأربع التي رأيناها من الانتقاء:

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

والخطوة الأخيرة تستحق كلمة: أغلب الفرق لا تبني الإصدار من جهاز أحد، وإنما تجعل خط 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، لا تنس أن تنهي الجلسة بالأمر 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 commitGit يتهم «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:
- اختبر الأمر على الطرفين قبل البدء: شغله على 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 Commit | git 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
- أنشئ مستودعاً بوسم v1.0.0، ثم أضف على main ميزة غير مكتملة وإصلاحاً منفصلاً، وأنشئ فرع إصدار من الوسم، وانقل الإصلاح وحده بالأمر
git cherry-pick -x، ثم تحقق بالأمرgit cherry -v. - ضع وسماً مشروحاً v1.0.1، وادفع الفرع، وتحقق بالأمر
git ls-remote --tagsأن الوسم لم يصل، ثم ادفعه. - اكتب إصلاحاً يغير دالة غير موجودة في فرع الإصدار، وحاول أن تنقله، واقرأ التعارض، ثم ألغه بالأمر
--abort. - أنشئ عشرين Commit، واجعل واحداً منها يعطل اختباراً، وآخر لا يستورد، ثم ابحث بالأمر
git bisect runمع رمز الخروج 125، وعد الخطوات. - أعد التجربة دون حذف
__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 في العمل اليومي بعد تقسيمه إلى أربعة مقالات.