Skip to content

Latest commit

 

History

History
174 lines (126 loc) · 4.62 KB

2. Git Bisect.md

File metadata and controls

174 lines (126 loc) · 4.62 KB
Raw

Git Bisect

Git Bisect is a powerful debugging tool that helps you find the commit that introduced a bug by performing a binary search through your project’s commit history.

1. What is Git Bisect?

Git bisect identifies the "bad" commit (the one that introduced the bug) by splitting the range of commits into halves and testing each until the problematic commit is found.

Key Points:

  • Efficiently locates the commit causing an issue.
  • Automates the debugging process by narrowing down the commit range.

2. When to Use Git Bisect

  • Bug Identification: When a previously working feature breaks.
  • Regression Testing: To pinpoint the commit introducing a regression.
  • Collaborative Projects: To debug issues introduced by changes in a team environment.

3. How Git Bisect Works

  1. Start Bisecting: Mark the current commit as bad (bug present).
  2. Identify a Good Commit: Specify the last known good commit (bug not present).
  3. Test Commits: Git checks out a commit in the middle of the range for testing.
  4. Mark Results: You mark each commit as good or bad based on your tests.
  5. Locate the Bad Commit: Git narrows the range until the problematic commit is found.

4. Using Git Bisect

Step 1: Start Bisecting

git bisect start

Step 2: Mark the Current Commit as Bad

git bisect bad

Step 3: Mark a Known Good Commit

Identify a commit where the bug wasn’t present:

git bisect good <commit-hash>

Step 4: Test Each Commit

Git checks out a commit for you to test. After testing:

  • If the bug is present, mark the commit as bad: 
    git bisect bad
  • If the bug is not present, mark the commit as good: 
    git bisect good

Step 5: Repeat Until the Bad Commit is Found

Git continues the process until it identifies the problematic commit. You’ll see output like:

<commit-hash> is the first bad commit

5. Automating Bisect

You can automate testing with a script. For example:

  1. Write a script that returns 0 for good and 1 for bad.
  2. Run bisect with the script: 
    git bisect run ./test-script.sh

6. Ending Bisect

Once the bad commit is found, reset your repository to the original state:

git bisect reset

7. Example Workflow

Scenario

You notice a bug in your project after a recent commit. You know the bug wasn’t present five commits ago.

Steps:

  1. Start bisecting:

    git bisect start

  2. Mark the current commit as bad:

    git bisect bad

  3. Mark the last known good commit:

    git bisect good HEAD~5

  4. Test each commit:

    • If the bug is present: 
      git bisect bad
    • If the bug is absent: 
      git bisect good

  5. Git identifies the first bad commit:

    <commit-hash> is the first bad commit

  6. Reset your repository:

    git bisect reset

8. Best Practices for Using Git Bisect

  • Automate Testing: Use scripts to speed up the process for projects with consistent test criteria.
  • Document Findings: Record the cause of the issue and steps to resolve it after identifying the bad commit.
  • Use Tags or Messages: Use descriptive commit messages or tags to help you identify meaningful points in the history.

9. Common Commands

Command Description
git bisect start Start the bisect process.
git bisect bad Mark the current commit as bad.
git bisect good <commit-hash> Mark a specific commit as good.
git bisect run <script> Automate testing with a script.
git bisect reset End the bisect process and reset to the original state.

10. Frequently Asked Questions

Can I Bisect Across Multiple Branches?

Yes, as long as the commits in question are part of the same repository history.

What Happens If I Mark the Wrong Commit?

You can restart the bisect process using:

git bisect reset

Conclusion

Git bisect is a valuable tool for identifying the source of bugs or regressions efficiently. By combining manual or automated testing with Git’s binary search algorithm, you can debug faster and maintain project stability.

Next Steps: Custom Git Aliases