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
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 git://git.ipxe.org/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.
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
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 ..
bin/undionly.kpxe with the build that you are using.)
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 <firstname.lastname@example.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!