0001 Bisecting a bug
0002 +++++++++++++++
0003
0004 Last updated: 28 October 2016
0005
0006 Introduction
0007 ============
0008
0009 Always try the latest kernel from kernel.org and build from source. If you are
0010 not confident in doing that please report the bug to your distribution vendor
0011 instead of to a kernel developer.
0012
0013 Finding bugs is not always easy. Have a go though. If you can't find it don't
0014 give up. Report as much as you have found to the relevant maintainer. See
0015 MAINTAINERS for who that is for the subsystem you have worked on.
0016
0017 Before you submit a bug report read
0018 'Documentation/admin-guide/reporting-issues.rst'.
0019
0020 Devices not appearing
0021 =====================
0022
0023 Often this is caused by udev/systemd. Check that first before blaming it
0024 on the kernel.
0025
0026 Finding patch that caused a bug
0027 ===============================
0028
0029 Using the provided tools with ``git`` makes finding bugs easy provided the bug
0030 is reproducible.
0031
0032 Steps to do it:
0033
0034 - build the Kernel from its git source
0035 - start bisect with [#f1]_::
0036
0037 $ git bisect start
0038
0039 - mark the broken changeset with::
0040
0041 $ git bisect bad [commit]
0042
0043 - mark a changeset where the code is known to work with::
0044
0045 $ git bisect good [commit]
0046
0047 - rebuild the Kernel and test
0048 - interact with git bisect by using either::
0049
0050 $ git bisect good
0051
0052 or::
0053
0054 $ git bisect bad
0055
0056 depending if the bug happened on the changeset you're testing
0057 - After some interactions, git bisect will give you the changeset that
0058 likely caused the bug.
0059
0060 - For example, if you know that the current version is bad, and version
0061 4.8 is good, you could do::
0062
0063 $ git bisect start
0064 $ git bisect bad # Current version is bad
0065 $ git bisect good v4.8
0066
0067
0068 .. [#f1] You can, optionally, provide both good and bad arguments at git
0069 start with ``git bisect start [BAD] [GOOD]``
0070
0071 For further references, please read:
0072
0073 - The man page for ``git-bisect``
0074 - `Fighting regressions with git bisect <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_
0075 - `Fully automated bisecting with "git bisect run" <https://lwn.net/Articles/317154>`_
0076 - `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_
