Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: bug-bisect: rewrite to better match the other bisecting text
Rewrite the short document on bisecting kernel bugs. The new text
improves .config handling, brings a mention of 'git bisect skip', and
explains what to do after the bisection finished -- including trying a
revert to verify the result. The rewrite at the same time removes the
unrelated and outdated section on 'Devices not appearing' and replaces
some sentences about bug reporting with a pointer to the document
covering that topic in detail.
This overall brings the approach close to the one in the recently added
text Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst.
As those two texts serve a similar purpose for different audiences,
mention that document in the head of this one and outline when the
other might be the better one to follow.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Petr Tesarik <petr@tesarici.cz>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/74dc0137dcc3e2c05648e885a7bc31ffd39a0890.1724312119.git.linux@leemhuis.info
authored by
Thorsten Leemhuis
and committed by
Jonathan Corbet
cbbdb6c6
a4931bb8
+118
-49
+117
-49
Documentation/admin-guide/bug-bisect.rst
+117
-49
Documentation/admin-guide/bug-bisect.rst
···
1
-
Bisecting a bug
2
-
+++++++++++++++
1
+
.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
2
+
.. [see the bottom of this file for redistribution information]
3
3
4
-
Last updated: 28 October 2016
4
+
======================
5
+
Bisecting a regression
6
+
======================
5
7
6
-
Introduction
7
-
============
8
+
This document describes how to use a ``git bisect`` to find the source code
9
+
change that broke something -- for example when some functionality stopped
10
+
working after upgrading from Linux 6.0 to 6.1.
8
11
9
-
Always try the latest kernel from kernel.org and build from source. If you are
10
-
not confident in doing that please report the bug to your distribution vendor
11
-
instead of to a kernel developer.
12
+
The text focuses on the gist of the process. If you are new to bisecting the
13
+
kernel, better follow Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
14
+
instead: it depicts everything from start to finish while covering multiple
15
+
aspects even kernel developers occasionally forget. This includes detecting
16
+
situations early where a bisection would be a waste of time, as nobody would
17
+
care about the result -- for example, because the problem happens after the
18
+
kernel marked itself as 'tainted', occurs in an abandoned version, was already
19
+
fixed, or is caused by a .config change you or your Linux distributor performed.
12
20
13
-
Finding bugs is not always easy. Have a go though. If you can't find it don't
14
-
give up. Report as much as you have found to the relevant maintainer. See
15
-
MAINTAINERS for who that is for the subsystem you have worked on.
21
+
Finding the change causing a kernel issue using a bisection
22
+
===========================================================
16
23
17
-
Before you submit a bug report read
18
-
'Documentation/admin-guide/reporting-issues.rst'.
24
+
*Note: the following process assumes you prepared everything for a bisection.
25
+
This includes having a Git clone with the appropriate sources, installing the
26
+
software required to build and install kernels, as well as a .config file stored
27
+
in a safe place (the following example assumes '~/prepared_kernel_.config') to
28
+
use as pristine base at each bisection step; ideally, you have also worked out
29
+
a fully reliable and straight-forward way to reproduce the regression, too.*
19
30
20
-
Devices not appearing
21
-
=====================
31
+
* Preparation: start the bisection and tell Git about the points in the history
32
+
you consider to be working and broken, which Git calls 'good' and 'bad'::
22
33
23
-
Often this is caused by udev/systemd. Check that first before blaming it
24
-
on the kernel.
34
+
git bisect start
35
+
git bisect good v6.0
36
+
git bisect bad v6.1
25
37
26
-
Finding patch that caused a bug
27
-
===============================
38
+
Instead of Git tags like 'v6.0' and 'v6.1' you can specify commit-ids, too.
28
39
29
-
Using the provided tools with ``git`` makes finding bugs easy provided the bug
30
-
is reproducible.
40
+
1. Copy your prepared .config into the build directory and adjust it to the
41
+
needs of the codebase Git checked out for testing::
31
42
32
-
Steps to do it:
43
+
cp ~/prepared_kernel_.config .config
44
+
make olddefconfig
33
45
34
-
- build the Kernel from its git source
35
-
- start bisect with [#f1]_::
46
+
2. Now build, install, and boot a kernel. This might fail for unrelated reasons,
47
+
for example, when a compile error happens at the current stage of the
48
+
bisection a later change resolves. In such cases run ``git bisect skip`` and
49
+
go back to step 1.
36
50
37
-
$ git bisect start
51
+
3. Check if the functionality that regressed works in the kernel you just built.
38
52
39
-
- mark the broken changeset with::
53
+
If it works, execute::
40
54
41
-
$ git bisect bad [commit]
55
+
git bisect good
42
56
43
-
- mark a changeset where the code is known to work with::
57
+
If it is broken, run::
44
58
45
-
$ git bisect good [commit]
59
+
git bisect bad
46
60
47
-
- rebuild the Kernel and test
48
-
- interact with git bisect by using either::
61
+
Note, getting this wrong just once will send the rest of the bisection
62
+
totally off course. To prevent having to start anew later you thus want to
63
+
ensure what you tell Git is correct; it is thus often wise to spend a few
64
+
minutes more on testing in case your reproducer is unreliable.
49
65
50
-
$ git bisect good
66
+
After issuing one of these two commands, Git will usually check out another
67
+
bisection point and print something like 'Bisecting: 675 revisions left to
68
+
test after this (roughly 10 steps)'. In that case go back to step 1.
51
69
52
-
or::
70
+
If Git instead prints something like 'cafecaca0c0dacafecaca0c0dacafecaca0c0da
71
+
is the first bad commit', then you have finished the bisection. In that case
72
+
move to the next point below. Note, right after displaying that line Git will
73
+
show some details about the culprit including its patch description; this can
74
+
easily fill your terminal, so you might need to scroll up to see the message
75
+
mentioning the culprit's commit-id.
53
76
54
-
$ git bisect bad
77
+
In case you missed Git's output, you can always run ``git bisect log`` to
78
+
print the status: it will show how many steps remain or mention the result of
79
+
the bisection.
55
80
56
-
depending if the bug happened on the changeset you're testing
57
-
- After some interactions, git bisect will give you the changeset that
58
-
likely caused the bug.
81
+
* Recommended complementary task: put the bisection log and the current .config
82
+
file aside for the bug report; furthermore tell Git to reset the sources to
83
+
the state before the bisection::
59
84
60
-
- For example, if you know that the current version is bad, and version
61
-
4.8 is good, you could do::
85
+
git bisect log > ~/bisection-log
86
+
cp .config ~/bisection-config-culprit
87
+
git bisect reset
62
88
63
-
$ git bisect start
64
-
$ git bisect bad # Current version is bad
65
-
$ git bisect good v4.8
89
+
* Recommended optional task: try reverting the culprit on top of the latest
90
+
codebase and check if that fixes your bug; if that is the case, it validates
91
+
the bisection and enables developers to resolve the regression through a
92
+
revert.
93
+
94
+
To try this, update your clone and check out latest mainline. Then tell Git
95
+
to revert the change by specifying its commit-id::
96
+
97
+
git revert --no-edit cafec0cacaca0
98
+
99
+
Git might reject this, for example when the bisection landed on a merge
100
+
commit. In that case, abandon the attempt. Do the same, if Git fails to revert
101
+
the culprit on its own because later changes depend on it -- at least unless
102
+
you bisected a stable or longterm kernel series, in which case you want to
103
+
check out its latest codebase and try a revert there.
104
+
105
+
If a revert succeeds, build and test another kernel to check if reverting
106
+
resolved your regression.
107
+
108
+
With that the process is complete. Now report the regression as described by
109
+
Documentation/admin-guide/reporting-issues.rst.
66
110
67
111
68
-
.. [#f1] You can, optionally, provide both good and bad arguments at git
69
-
start with ``git bisect start [BAD] [GOOD]``
112
+
Additional reading material
113
+
---------------------------
70
114
71
-
For further references, please read:
115
+
* The `man page for 'git bisect' <https://git-scm.com/docs/git-bisect>`_ and
116
+
`fighting regressions with 'git bisect' <https://git-scm.com/docs/git-bisect-lk2009.html>`_
117
+
in the Git documentation.
118
+
* `Working with git bisect <https://nathanchance.dev/posts/working-with-git-bisect/>`_
119
+
from kernel developer Nathan Chancellor.
120
+
* `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_.
121
+
* `Fully automated bisecting with 'git bisect run' <https://lwn.net/Articles/317154>`_.
72
122
73
-
- The man page for ``git-bisect``
74
-
- `Fighting regressions with git bisect <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_
75
-
- `Fully automated bisecting with "git bisect run" <https://lwn.net/Articles/317154>`_
76
-
- `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_
123
+
..
124
+
end-of-content
125
+
..
126
+
This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If
127
+
you spot a typo or small mistake, feel free to let him know directly and
128
+
he'll fix it. You are free to do the same in a mostly informal way if you
129
+
want to contribute changes to the text -- but for copyright reasons please CC
130
+
linux-doc@vger.kernel.org and 'sign-off' your contribution as
131
+
Documentation/process/submitting-patches.rst explains in the section 'Sign
132
+
your work - the Developer's Certificate of Origin'.
133
+
..
134
+
This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
135
+
of the file. If you want to distribute this text under CC-BY-4.0 only,
136
+
please use 'The Linux kernel development community' for author attribution
137
+
and link this as source:
138
+
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/bug-bisect.rst
139
+
140
+
..
141
+
Note: Only the content of this RST file as found in the Linux kernel sources
142
+
is available under CC-BY-4.0, as versions of this text that were processed
143
+
(for example by the kernel's build system) might contain content taken from
144
+
files which use a more restrictive license.
+1
MAINTAINERS
+1
MAINTAINERS
···
6719
6719
M: Thorsten Leemhuis <linux@leemhuis.info>
6720
6720
L: linux-doc@vger.kernel.org
6721
6721
S: Maintained
6722
+
F: Documentation/admin-guide/bug-bisect.rst
6722
6723
F: Documentation/admin-guide/quickly-build-trimmed-linux.rst
6723
6724
F: Documentation/admin-guide/reporting-issues.rst
6724
6725
F: Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst