Documentation/admin-guide/bug-bisect.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/bug-bisect.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/bug-bisect.rst
Extension
.rst
Size
7697 bytes
Lines
166
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
.. [see the bottom of this file for redistribution information]

======================
Bisecting a regression
======================

This document describes how to use a ``git bisect`` to find the source code
change that broke something -- for example when some functionality stopped
working after upgrading from Linux 6.0 to 6.1.

The text focuses on the gist of the process. If you are new to bisecting the
kernel, better follow Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
instead: it depicts everything from start to finish while covering multiple
aspects even kernel developers occasionally forget. This includes detecting
situations early where a bisection would be a waste of time, as nobody would
care about the result -- for example, because the problem happens after the
kernel marked itself as 'tainted', occurs in an abandoned version, was already
fixed, or is caused by a .config change you or your Linux distributor performed.

Finding the change causing a kernel issue using a bisection
===========================================================

*Note: the following process assumes you prepared everything for a bisection.
This includes having a Git clone with the appropriate sources, installing the
software required to build and install kernels, as well as a .config file stored
in a safe place (the following example assumes '~/prepared_kernel_.config') to
use as pristine base at each bisection step; ideally, you have also worked out
a fully reliable and straight-forward way to reproduce the regression, too.*

* Preparation: start the bisection and tell Git about the points in the history
  you consider to be working and broken, which Git calls 'good' and 'bad'::

     git bisect start
     git bisect good v6.0
     git bisect bad v6.1

  Instead of Git tags like 'v6.0' and 'v6.1' you can specify commit-ids, too.

1. Copy your prepared .config into the build directory and adjust it to the
   needs of the codebase Git checked out for testing::

     cp ~/prepared_kernel_.config .config
     make olddefconfig

2. Now build, install, and boot a kernel. This might fail for unrelated reasons,
   for example, when a compile error happens at the current stage of the
   bisection a later change resolves. In such cases run ``git bisect skip`` and
   go back to step 1.

3. Check if the functionality that regressed works in the kernel you just built.

   If it works, execute::

     git bisect good

   If it is broken, run::

     git bisect bad

   Note, getting this wrong just once will send the rest of the bisection
   totally off course. To prevent having to start anew later you thus want to
   ensure what you tell Git is correct; it is thus often wise to spend a few
   minutes more on testing in case your reproducer is unreliable.

   After issuing one of these two commands, Git will usually check out another
   bisection point and print something like 'Bisecting: 675 revisions left to
   test after this (roughly 10 steps)'. In that case go back to step 1.

   If Git instead prints something like 'cafecaca0c0dacafecaca0c0dacafecaca0c0da

Annotation

Implementation Notes