Git Notes Bisect

HEADS UP! Due to the recent reorg we highly recommend performing bisect on a clean repository, as it is highly likely that the whole directory structure will change upon checkout of old commits.

Git comes with a powerful tool for identifying a commit failure---git-bisect.

Documentation on using git-bisect can be found here. In this wiki, we will walk through an example using bisect to pin-point the commit that caused a firebot error tolerance warning.

First, what is the "bisection method"? You may have used this in school to find the solution to a nonlinear equation. Suppose we know that an error has occurred somewhere in the last 10 commits. Here's how a bisection would work to find the culprit.

C10 bad
C9 ?
C8 ?
C7 ?
C6 ?
C5 ?
C4 ?
C3 ?
C2 ?
C1 good

Now, we need to test C5 or C6 to see if this commit is good or bad. Suppose we test C6 and find it is "bad". Then we have

C10 bad
C9 ?
C8 ?
C7 ?
C6 bad
C5 ?
C4 ?
C3 ?
C2 ?
C1 good

and we know the culprit is between C1 and C6. Ok, now try C4... bad again. So we have

C10 bad
C9 ?
C8 ?
C7 ?
C6 bad
C5 ?
C4 bad
C3 ?
C2 ?
C1 good

Next we try C3... good!

C10 bad
C9 ?
C8 ?
C7 ?
C6 bad
C5 ?
C4 bad <= Culprit!
C3 good
C2 ?
C1 good

That means C4 is the culprit. Below we will show how to go to GitHub to see what files were modified in that commit.

OK, now let's get started using git-bisect for real.

While doing some development, you come across a problem that seems unrelated to the code you are working on. You have modified several of the tracked source code files in FDS_Source/. So, the first thing to do is to "stash" these changes.

$ git stash
Saved working directory and index state WIP on development: cb2e59e Merge pull request #2596 from gforney/development
HEAD is now at cb2e59e Merge pull request #2596 from gforney/development

You are now working from a clean copy of Git-421-gcb2e59e.

$ git describe
Git-421-gcb2e59e

You may also want to work from a repo with no "untracked" files, since, due to the recent reorg, the directory structure is likely to change upon checkout of old commits for testing.

The next step is to give git bisect a "good" state to bookend the problem. This is probably the trickiest part of the whole process. It usually involves some guesswork. The easiest thing to do is to check our Firebot Build Status page and copy the Git revision of a "Build success!" Unfortunately, we have not had a success lately, so you guess at the revision that should work.

In lieu of looking at the build status page, you can always just look at the log. I like to use the --oneline option for a concise description of the commits.

$ git log --oneline
cb2e59e Merge pull request #2596 from gforney/development
349a596 Merge branch 'development' of git://github.com/firemodels/fds-smv into development
9c8ba03 firebot: output timing info for ways that firebot can finish
784c573 Merge pull request #2593 from mcgratta/development
ee4fa68 Merge remote branch 'firemodels/development' into development
9643e80 Merge pull request #2592 from gforney/development
d2aef85 firebot: correction to email option in run_firebot
9d6788f Merge pull request #2591 from gforney/development
0a47684 Make the architecture optimization automatic for xlf on power architecture so it doesn't only target power7. Also provide flags for aix.
34b6d4e Document the BUILD_DATE_XLF variable
83b9bcf FDS Source: add HRRPUV REAC output quantity (in development)
...

This keeps going. But let's try 83b9bcf to see if it works.

$ git checkout 83b9bcf
Note: checking out '83b9bcf'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b new_branch_name

HEAD is now at 83b9bcf... FDS Source: add HRRPUV REAC output quantity (in development)

Compile and run the test case to confirm that 83b9bcf is indeed a "good" commit. Supposing it is, you are ready to start the bisection. In this case, since you currently have the "good" commit checked out, you need to explicitly tell git bisect which commit is "bad".

$ git bisect start
$ git bisect bad cb2e59e
$ git bisect good 83b9bcf
Bisecting: 10 revisions left to test after this (roughly 4 steps)
[9d6788f6ccb5c624057c50e7d60dd74ac169b011] Merge pull request #2591 from gforney/development

Git bisect grabbed the commit roughly in the middle of the good and bad commits you listed and checked out that commit for you (9d6788f). Now compile and run the test case. Pass. So...

$ git bisect good
Bisecting: 6 revisions left to test after this (roughly 3 steps)
[64d49a0b9535f97fc7a1f7917768071b15b93ba7] FDS Source: Fix undefined variables.

Fail...

$ git bisect bad
Bisecting: 1 revision left to test after this (roughly 1 step)
[2c3689b58843414de0465cc4d285c1715ef0016f] FDS Verification: Replace couch.fds for room_fire.fds.

Fail...

$ git bisect bad
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[63112ceb6140682b6f312086bbe05593f26218c7] FDS Source: Issue 2439. Fix problem with EXPOSED surfaces near mesh boundaries.

Fail...

$ git bisect bad
63112ceb6140682b6f312086bbe05593f26218c7 is the first bad commit
commit 63112ceb6140682b6f312086bbe05593f26218c7
Author: mcgratta <[email protected]>
Date:   Fri Aug 7 10:40:47 2015 -0400

    FDS Source: Issue 2439. Fix problem with EXPOSED surfaces near mesh boundaries.

:040000 040000 ca84c0a5d9dd52a02f544902b87effc235bf9959 053003060d2d55e81a0d4476c8350e97c4d8ffdd M	FDS_Source
:040000 040000 63d9b4bf1e7d04a6270155d45b9cfd9a05601343 01b9bf5d587b244a64ddf9f2457dc4de5f0e81b9 M	Validation

So, now you can email Kevin and ask him to fix the problem :).

Next, you need to quit bisect.

$ git bisect reset

If you forget to do the reset, the next time you try to run bisect you may get an error of the type

fatal: invalid reference: <branch>

To fix this, do

$ rm .git/BISECT_* # note: NO SPACES between _ and *

Finally, you need to get back to your development branch and apply your stashed changes.

$ git checkout development
Previous HEAD position was 83b9bcf... FDS Source: add HRRPUV REAC output quantity (in development)
Switched to branch 'development'

$ git stash apply -q