Finding a bug using git-bisect

git-bisect is a powerful tool for quickly tracking down the precise change that introduced a bug in iPXE. If you are encountering a problem with the latest version of iPXE, and you know that an older version of iPXE does not have the same problem, then you can use git-bisect.

Once you have identified the precise change that introduced the bug, you can inform the developers, who can then use this information to help solve your problem.

First, check out a copy of the iPXE source tree:

  git clone https://github.com/ipxe/ipxe.git

and verify that you are able to build iPXE:

  cd ipxe/src
  make bin/undionly.kpxe

For the sake of this tutorial, it is assumed that you want to use the undionly.kpxe build of iPXE. If you want to use a different build of iPXE (e.g. a bootable ISO with drivers for an Intel e1000 network card) then you should replace bin/undionly.kpxe with the build you want (e.g. bin/e1000.iso).

Test the iPXE that you have just built, and confirm that the bug is still present in this latest version of iPXE. (Code changes frequently, and it is possible that a bug you have encountered has already been fixed.)

To start bisecting, inform git-bisect that the latest version of the code has a bug:

  cd ..
  git bisect start
  git bisect bad

Tell git-bisect which older version of iPXE does not have the bug. For example, if you know that the bug was not present in version 1.0.0, you can use:

  git bisect good v1.0.0

git-bisect will choose a version midway between your stated “good” and “bad” versions. For example:

  [mcb30@dolphin]$ git bisect good v1.0.0
  Bisecting: 187 revisions left to test after this (roughly 8 steps)
  [28934ee] [retry] Hold reference while timer is running

Build and test the version that git-bisect has selected:

  cd src
  make bin/undionly.kpxe
  cd ..

(Again, replace bin/undionly.kpxe with the build that you are using.)

Inform git-bisect whether or not its chosen version has the bug:

  git bisect bad     (if the bug is present)
  git bisect good    (if the bug is not present)

git-bisect will choose another new version for you to test. Build and test this new version, and again report the result using either git bisect bad or git bisect good. Repeat this process until you see a message such as

  7e1b1d6145a36ae7ad1c58663c7116f96fada1f9 is the first bad commit
  
  commit 7e1b1d6145a36ae7ad1c58663c7116f96fada1f9
  Author: Michael Brown <mcb30@ipxe.org>
  Date:   Thu Nov 25 23:45:30 2010 +0000
  
      [vlan] Allow duplicate VLAN creation attempts

If you have followed the process correctly, then this is the commit that introduced the bug. You can now contact the developers with details of your bug, including the “first bad commit” (7e1b1d6145a36ae7ad1c58663c7116f96fada1f9 in the above example).

When you have finished, tell git-bisect to clean up your iPXE source tree and restore it to the latest version:

  git bisect reset

Thank you for helping to improve iPXE!