This error occurs when you try to run git bisect commands like 'git bisect run', 'git bisect good', or 'git bisect bad' without first initializing a bisect session and providing both good and bad commit boundaries.
The error "You need to start by 'git bisect start'" indicates that you're attempting to use git bisect commands before properly initializing a bisect session. Git bisect is a binary search tool that requires you to define a search range by marking both a "good" commit (where the bug doesn't exist) and a "bad" commit (where the bug is present). Git bisect uses binary search to efficiently find the commit that introduced a bug. It needs both boundary commits to know which range of commits to search through. Without these boundaries, git bisect cannot determine which commits to test. This error commonly appears when developers try to run `git bisect run <script>` immediately without first establishing the commit range, or when they mark only one boundary (good or bad) but not both.
Initialize the bisect session with the start command:
git bisect startThis puts Git into bisect mode and prepares it to track good and bad commits. You should see no output if successful.
Identify a commit where the bug is present. Often this is your current HEAD:
# Mark current commit as bad
git bisect bad
# Or mark a specific commit as bad
git bisect bad HEAD
git bisect bad abc1234Git will acknowledge the bad commit and wait for a good commit.
Find a commit where you're confident the bug didn't exist. This could be a previous release tag or an older commit:
# Mark a specific commit as good
git bisect good v1.0.0
git bisect good abc1234
# Or if you're on the good commit
git bisect goodAfter marking both boundaries, Git will checkout a commit in the middle for testing.
You can specify both boundaries directly with the start command:
# git bisect start <bad> <good>
git bisect start HEAD v1.0.0
git bisect start abc1234 def5678This is equivalent to running start, bad, and good as separate commands but is more concise.
Once both boundaries are set, you can use automated testing:
git bisect run ./test-script.shYour test script should exit with code 0 for "good" (no bug) and non-zero (1-127, except 125) for "bad" (bug present). Exit code 125 tells git to skip the current commit.
If not using automated testing, test each commit Git checks out:
# Run your tests, then mark the result
git bisect good # if bug is NOT present
git bisect bad # if bug IS presentGit will continue checking out middle commits until it finds the first bad commit.
When Git finds the culprit commit, it will display it. Then clean up:
# Return to your original branch/commit
git bisect resetThis ends the bisect session and returns your working directory to the state before you started bisecting.
If you're unsure whether a bisect session is active or what state it's in:
# View the bisect log
git bisect log
# View current bisect state
git bisect visualizeIf no session is active, these commands will indicate that you need to start one.
Complete bisect workflow example:
# 1. Start the session
git bisect start
# 2. Mark current as bad
git bisect bad HEAD
# 3. Mark a known good commit
git bisect good v2.0.0
# 4. Git checks out a middle commit - test it
# ... run your tests ...
# 5. Mark result and repeat until found
git bisect good # or git bisect bad
# 6. When found, Git shows the first bad commit
# 7. Clean up
git bisect resetUsing custom terms instead of good/bad:
For finding non-regression changes (like performance improvements), use custom terms:
git bisect start --term-old=slow --term-new=fast
git bisect fast HEAD
git bisect slow v1.0.0Skipping untestable commits:
If a commit can't be tested (e.g., build is broken), skip it:
git bisect skipGit will select a nearby commit instead.
Recovering from mistakes:
If you accidentally mark a commit wrong:
git bisect log > /tmp/bisect.log
# Edit /tmp/bisect.log to remove wrong entries
git bisect reset
git bisect replay /tmp/bisect.logLimiting bisect to specific paths:
If the bug is in a specific directory:
git bisect start -- path/to/directoryThis limits the search to commits that modified those paths.
Non-executable script gotcha:
If using git bisect run, ensure your script is executable:
chmod +x ./test-script.shA non-executable script will exit with code 126 or 127, causing bisect to fail on every commit.
warning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server