باگ هست؛ اما نمی‌دانیم کدام commit آوردشThe bug is real, but which commit introduced it?

تیم می‌گوید نسخهٔ قدیمی رفتار درست داشته، commit امروز خراب است و log پیام روشنی ندارد. فصل ۱۱ کمک کرد یک patch شناخته‌شده را انتخاب کنی؛ این بار خود commit مقصر را نمی‌دانیم. می‌توانیم به هر نسخه برویم و همان آزمون را اجرا کنیم. سؤال این نیست که «کدام commit مشکوک به نظر می‌رسد؟»؛ سؤال این است که «مرز سالم و خراب دقیقاً کجاست؟»

The team says an older version behaved correctly, today's commit is broken, and the log message is unhelpful. Chapter 11 let you select a known patch; this time we do not know the culprit. We can check out versions and run the same test. The question is not “which commit looks suspicious?” but “where exactly is the good/bad boundary?”

اگر ۶۴ commit را از اول تا آخر آزمایش کنی، شاید ۶۴ بار زمان ببرد. اما وقتی نتیجهٔ یک commit میانی را بدانی، با فرض یکنواختی باگ می‌فهمی بازهٔ باقی‌مانده کدام نیمه است. این ایدهٔ جست‌وجوی دودویی است؛ git bisect انتخاب commitهای میانی و نگه‌داشتن بازه را انجام می‌دهد، ولی قضاوت دربارهٔ نتیجه هنوز با آزمون توست.

A linear scan may take 64 tests. But if you test a middle revision and the regression is monotonic, you know which half remains. That is binary-search intuition. git bisect selects intermediate commits and tracks the remaining range, while your test still decides good versus bad.

bisect فقط به دو نشانه و یک آزمون نیاز داردBisect needs two labels and a test

به Git دو لنگر می‌دهی: یک commit که مطمئنی خراب است، و یک یا چند commit که مطمئنی هنوز سالم‌اند. سپس هر commit پیشنهادی را با همان آزمون می‌سنجی و نتیجه را ثبت می‌کنی. Git وسط بعدی را انتخاب می‌کند تا وقتی به اولین commit خراب در محدودهٔ قابل‌جست‌وجو برسد.

Give Git two anchors: a commit known to be bad and one or more commits known to be good. Test each suggested revision with the same check and report the result. Git chooses the next candidate until it identifies the first bad commit within the searchable range.

مدلِ «هرچه جلوتر برویم خراب‌تر می‌شود» مهم است. اگر باگ در یک commit می‌آید و commit بعدی آن را موقتاً پنهان می‌کند، یا چند پسرفت مستقل داری، پاسخ «اولین خراب» ممکن است به سؤال واقعی‌ات جواب ندهد. bisect دادهٔ درست را از تست درست بهتر نمی‌کند.

The assumption that the bug stays present in later commits matters. If a later commit temporarily hides it, or several independent regressions exist, “first bad” may not answer your real question. Bisect cannot turn a poor test into good evidence.

یک مرز دیگر هم mergeها هستند: تاریخچه شاخه‌دار نیست همیشه یک خط. در حالت معمول bisect مسیر قابل‌دسترسی را دنبال می‌کند؛ --first-parent سؤال دیگری می‌پرسد و فقط مسیر اصلی را از mergeها می‌گذراند، برای پیدا کردن mergeای که پسرفت را وارد ادغام کرده. آن را بی‌دلیل روشن نکن؛ ممکن است دیگر دنبال commit داخل شاخهٔ ادغام‌شده نباشی.

Merge history adds another boundary: history is not always a single line. Normal bisect searches reachable history; --first-parent asks a different question by following only the mainline through merges, useful for finding the merge that brought a regression into integration. Do not enable it casually: you may stop searching for the original commit inside the merged branch.

آزمایش دستی: مرز خوب و خراب را پیدا کنManual experiment: find the good/bad boundary

این آزمایش یک مخزن تازه می‌سازد؛ فقط داخل همان پوشه اجرا کن. ۱۲ commit با پیام‌های تقریباً یکسان داریم و یکی از آن‌ها خروجی برنامه را از ۴۲ به ۴۱ عوض می‌کند. قبل از bisect، anchor سالم را tag می‌کنیم تا حدس خوبمان شناسه داشته باشد.

This experiment creates a fresh repository; run it only in that folder. It makes 12 similarly named commits, one of which changes the program's output from 42 to 41. Before bisect, tag the known-good anchor so it has a stable name.

mkdir bisect-manual
cd bisect-manual
git init -q
git config user.name "Git Learner"
git config user.email learner@example.test
printf 'print(42)\n' > app.py
git add app.py && git commit -m "Refresh sample"
git tag known-good
for n in $(seq 1 12); do
  if [ "$n" = 7 ]; then printf 'print(41)\n' > app.py
  else printf 'sample %s\n' "$n" >> notes.txt
  fi
  git add app.py notes.txt
  git commit -m "Refresh sample"
done
python3 app.py

در این نسخه، خروجی ۴۱ یعنی پسرفت دیده می‌شود؛ tag known-good به نسخه‌ای با خروجی ۴۲ می‌رسد. اسم commitها عمداً سرنخ نیست. اگر Python 3 در محیطت نیست، قبل از شروع ابزار مناسب را آماده کن؛ نبودن runtime را به‌اشتباه خراب علامت نزن.

Here, output 41 means the regression is present; known-good names a revision that prints 42. Commit messages are deliberately unhelpful. If Python 3 is unavailable, prepare the runtime before starting; do not mislabel a missing runtime as a bad revision.

git bisect start
git bisect bad
git bisect good known-good
python3 app.py
# record exactly one result for this checked-out commit:
git bisect good
# or: git bisect bad
# repeat test + mark until Git identifies the boundary
git bisect log
git show --stat --oneline BISECT_OID
git bisect reset

بعد از دو نشانه، Git یک commit را checkout می‌کند و تعداد تقریبی باقی‌مانده‌ها را می‌گوید. خروجی برنامه را همان‌جا بخوان و فقط نتیجهٔ همان گزینهٔ آزمایشی را ثبت کن. وقتی تمام شد، BISECT_OID را با شناسهٔ واقعی گزارش جایگزین کن و patch commit را ببین. آخر کار reset لازم است: حالت bisect را می‌بندد و به شاخه/HEAD آغاز برمی‌گردد.

After both labels, Git checks out a candidate and reports an approximate remainder. Run the program there and mark only that candidate's result. When complete, replace BISECT_OID with the reported ID and inspect its patch. Finish with reset to end the session and return to the original branch/HEAD.

در اجرای واقعی، فرمان دستی git bisect good را وقتی می‌زنی که آزمون را اجرا کرده‌ای و خروجی ۴۲ بوده؛ اگر ۴۱ بود bad. این متن دستورهای دو حالت را نشان می‌دهد تا جای هم عوضشان نکنی. شناسه و تعداد گام‌ها بسته به تاریخچه فرق می‌کند.

In the actual run, enter git bisect good only after observing 42; enter bad after 41. The two alternatives are shown so you do not confuse them. IDs and step counts depend on history.

Bisecting: 6 revisions left to test after this (roughly 3 steps)
[candidate checkout]
$ python3 app.py
42
$ git bisect good
Bisecting: 2 revisions left to test after this (roughly 2 steps)
...
1234abc is the first bad commit

این خروجی نمونه‌ای است، نه نتیجهٔ ثابت همین تاریخچه: «roughly» خودش می‌گوید تعداد تقریبی است. مهم این است که هر بار اول گزینهٔ آزمایشی را واقعاً آزمایش کنی و بعد برچسب همان نتیجه را بزنی.

This is illustrative, not a guaranteed transcript for this history; “roughly” signals an estimate. The important order is to test the checked-out candidate first, then label that result.

اولین commit خراب را ببین؛ نتیجه را بازرسی کنInspect the reported first bad commit

پیام پایانی bisect می‌گوید کدام commit در محدودهٔ بررسی‌شده اولین بار از سالم به خراب می‌رسد. این نتیجه ثابت نمی‌کند پیام commit دربارهٔ bug حرف می‌زند؛ آن را از روی محتوای واقعی commit بررسی کن.

Bisect's final message identifies the first good-to-bad transition within the searched range. It does not prove the commit message mentions the bug; inspect the actual change.

git show --stat --oneline BISECT_OID
git show BISECT_OID -- app.py
git bisect log
git bisect reset

در این آزمایش patch باید خروجی را از ۴۲ به ۴۱ عوض کرده باشد. git bisect log نشان می‌دهد کدام نسخه‌ها را good/bad اعلام کرده‌ای؛ اگر در میانهٔ کار برچسبی را اشتباه زدی، همین log مبنای بازبینی است. بعد از reset، commit مقصر را می‌توانی با شاخه یا tag جداگانه نام‌گذاری کنی؛ session bisect اشاره‌گر دائمی پروژه نیست.

In this experiment, the patch should change output from 42 to 41. git bisect log records which revisions you marked good or bad; if you mislabelled one, use this log to review. After reset, preserve the culprit with a branch or tag if useful; a bisect session is not a permanent project ref.

وقتی آزمون روشن است، bisect را خودکار کنAutomate bisect when the test is unambiguous

تا اینجا خودت برنامه را اجرا و برچسب را وارد کردی. اگر آزمون کوتاه، تکرارپذیر و مستقل است، Git می‌تواند آن را در هر گزینهٔ آزمایشی اجرا کند. اما «خودکار» یعنی تصمیم‌گیری طبق کد خروجی؛ اگر قرارداد کدها را نفهمی، ممکن است همهٔ خطاهای محیط را خراب اعلام کنی.

So far you ran the program and entered each label yourself. If the check is short, repeatable, and independent, Git can run it at every candidate. But “automated” means decisions follow exit codes; misunderstand the contract and environment failures may all be marked bad.

در قرارداد فعلی Git، ۱۲۶ و ۱۲۷ هم داخل بازهٔ خراب قرار می‌گیرند: shell آن‌ها را برای «پیدا شد ولی اجرا نشد» و «فرمان پیدا نشد» به‌کار می‌برد. پس اگر اسکریپت یا runtime نصب نیست، مراقب باش آن را پسرفت برنامه جا نزنی؛ با بررسی صریح وابستگی‌ها skip کن یا اجرای bisect را متوقف کن. کدهای دیگر، از جمله خروجی‌های بزرگ‌تر از ۱۲۷، اجرای خودکار را abort می‌کنند.

Under Git's documented contract, 126 and 127 also fall in the bad range: shells use them for “found but not executable” and “command not found.” So if a script or runtime is missing, do not mistake that for an application regression; detect the prerequisite explicitly and skip or stop. Other statuses, including values above 127, abort the automated run.

bisect به‌اندازهٔ آزمونت قابل‌اعتماد استBisect is only as reliable as its test

اگر تست گاهی با شبکه fail شود، زمان اجرا را بسنجد، یا خودش فایل ردیابی‌شده را تغییر دهد، برچسب‌هایی که ثبت می‌کنی معنای ثابتی ندارند. bisect با صداقت هرچه داده‌ای بازه را کم می‌کند؛ نمی‌فهمد آزمونت ناعادلانه بوده.

If a test sometimes fails because of the network, depends on timing, or modifies tracked files, your labels have no stable meaning. Bisect faithfully narrows the range based on your input; it cannot detect that your test was unfair.

قبل از شروع، آزمون را چند بار روی همان commit اجرا کن و مطمئن شو نتیجه ثابت است. آن را فقط به رفتار مورد جست‌وجو وصل کن، نه به هشدار unrelated یا شکست ساخت ناشی از نصب‌نبودن dependency. اسکریپت را بیرون مخزن نگه دار یا مطمئن شو اجرای آن ردیابی‌شده وضعیت را تغییر نمی‌دهد؛ آزمایش destructive ممنوع.

Before starting, run the check several times on the same commit and confirm stable results. Tie it only to the behavior under investigation, not unrelated warnings or a build failure caused by a missing dependency. Keep the script outside the repository or ensure it does not alter tracked state; destructive tests are out of scope.

نسخه‌ای که نمی‌شود ساخت را skip کن؛ ابهام را هم بپذیرSkip an unbuildable revision—and accept the ambiguity

یک گزینهٔ آزمایشی به dependency قدیمی نیاز دارد که دیگر در دسترس نیست. این نسخه را نمی‌توانی با همان آزمون بسنجی؛ git bisect skip آن را نه خوب می‌نامد و نه بد. Git از اطرافش جست‌وجو می‌کند.

A candidate requires an unavailable old dependency. You cannot run the same check there; git bisect skip marks it neither good nor bad, and Git searches around it.

git status --short --branch
git bisect skip
git bisect log

اگر commit خراب میان چند commit skipشده باشد، Git ممکن است فقط مجموعه‌ای از گزینهٔ آزمایشیها را گزارش کند و نتواند یکی را با قطعیت اولین خراب اعلام کند. skip را برای راحتی نزن؛ دلیلش را یادداشت کن، تعداد skipها را محدود کن، و اگر محدوده مبهم شد dependency یا محیط قدیمی را فراهم کن و آزمایش را دوباره انجام بده.

If the culprit lies among skipped commits, Git may report a set of candidates rather than one certain first bad commit. Do not skip for convenience: record why, keep skips limited, and if the result is ambiguous, restore the old dependency/environment and rerun the test.

جلسه را reset کن؛ وسطش روی شاخهٔ دیگری کار نکنReset the session; do not switch away and keep working

bisect برای آزمودن هر گزینهٔ آزمایشی، checkout را جابه‌جا می‌کند و معمولاً در حالت جداشده HEAD می‌مانی. پایان طبیعی آزمایش git bisect reset است؛ این فرمان session را می‌بندد و به شاخه/commit آغاز برمی‌گرداند.

Bisect checks out each candidate, usually leaving you in detached HEAD. End the experiment with git bisect reset; it closes the session and returns to the starting branch/commit.

اگر قبل از reset شاخه را دستی عوض کنی، برچسب‌گذاری ممکن است متوقف یا گیج‌کننده شود. git bisect log را برای ثبت تصمیم‌ها بخوان؛ اگر برچسبی غلط بوده، session را با log بررسی و اصلاح کن. کار آزمایشی را در شاخهٔ bisect commit نکن مگر عمداً و با درک جداشده HEAD.

Manually switching branches before reset can interrupt or confuse the session. Read git bisect log to review decisions; if a label was wrong, use the log to correct the session. Do not commit incidental work on a bisect candidate unless you deliberately understand detached HEAD.

وقتی نتیجه عجیب است، اول فرض‌ها را بررسی کنWhen the result looks strange, check your assumptions

اگر bisect نتیجهٔ عجیب داد، اول خود آزمون و دو مرز سالم/خراب را زیر سؤال ببر. این ابزار فقط بر اساس جواب‌هایی که تو به آن می‌دهی دامنه را نصف می‌کند؛ اگر آزمون ناپایدار یا مرز اولیه اشتباه باشد، سرعت بیشتر فقط تو را سریع‌تر به جواب غلط می‌رساند.

Before repairing anything, inspect git bisect log and both endpoints. Change one assumption—anchor or test—not both at once. That lets you see which correction changed the result.

پروژهٔ کوچک: پسرفت را پیدا کنMini-project: find the regression

mkdir bisect-capstone && cd bisect-capstone
git init -q
git config user.name "Git Learner"
git config user.email learner@example.test
printf 'print(42)\n' > app.py
git add app.py && git commit -m "Refresh sample"
git tag known-good
for n in $(seq 1 40); do
  if [ "$n" = 23 ]; then printf 'print(41)\n' > app.py
  else printf 'sample %s\n' "$n" >> notes.txt
  fi
  git add app.py notes.txt
  git commit -m "Refresh sample"
done
python3 app.py

cat > ../test-bisect.sh <<'EOF'
#!/bin/sh
command -v python3 >/dev/null 2>&1 || exit 125
actual=$(python3 app.py 2>/dev/null) || exit 1
[ "$actual" = "42" ]
EOF
chmod +x ../test-bisect.sh
git bisect reset
git bisect start
git bisect bad HEAD
git bisect good known-good
git bisect run ../test-bisect.sh
git bisect log
git show --stat --oneline BISECT_OID
git show BISECT_OID -- app.py
git bisect reset

تمرین‌ها: از پیش‌بینی تا پروندهٔ واقعیExercises: from prediction to real incidents

اینجا هدف حفظ دستور bisect نیست. بعضی تمرین‌ها ازت می‌خواهند تعداد تقریبی آزمون‌ها را پیش‌بینی کنی، بعضی کیفیت آزمون را بسنجی و بعضی تشخیص بدهی چه وقت skip باعث می‌شود جواب نهایی مبهم بماند.

Whenever a result needs interpretation, state what you know and what remains unproven. Bisect builds its answer from your labels.

از commit مقصر به سیاست کار تیمیFrom the culprit commit to team workflow

تا اینجا دنبال یک commit مقصر بودیم. از فصل بعد زاویه عوض می‌شود: چطور تیم طوری شاخه بسازد و زود ادغام کند که فاصله‌ها و درگیری‌های بزرگ کمتر شوند؟

Bisect helped locate a change in history. But if regressions are usually found late, the problem may not be one commit: branches may live too long or integration may happen too rarely. Chapter 13 moves from one repository to team policy: how long should branches live, and how often should integration happen?

مرور کوتاهQuick reference

برای قرارداد دقیق نسخهٔ نصب‌شده، راهنمای رسمی bisect را ببین. نوع گراف، mergeها، anchorها و commitهای skipشده روی مسیر جست‌وجو اثر می‌گذارند؛ تعداد مراحل را وعده نده و آزمون را بخشی از نتیجه بدان.

For the exact contract in your installed version, consult the official git bisect manual. Graph shape, merges, anchors, and skipped commits affect the search; do not promise a fixed number of steps, and treat the test as part of the result.