Documentation/maintainer/rebasing-and-merging.rst

Source file repositories/reference/linux-study-clean/Documentation/maintainer/rebasing-and-merging.rst

File Facts

System
Linux kernel
Corpus path
Documentation/maintainer/rebasing-and-merging.rst
Extension
.rst
Size
11573 bytes
Lines
223
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

====================
Rebasing and merging
====================

Maintaining a subsystem, as a general rule, requires a familiarity with the
Git source-code management system.  Git is a powerful tool with a lot of
features; as is often the case with such tools, there are right and wrong
ways to use those features.  This document looks in particular at the use
of rebasing and merging.  Maintainers often get in trouble when they use
those tools incorrectly, but avoiding problems is not actually all that
hard.

One thing to be aware of in general is that, unlike many other projects,
the kernel community is not scared by seeing merge commits in its
development history.  Indeed, given the scale of the project, avoiding
merges would be nearly impossible.  Some problems encountered by
maintainers result from a desire to avoid merges, while others come from
merging a little too often.

Rebasing
========

"Rebasing" is the process of changing the history of a series of commits
within a repository.  There are two different types of operations that are
referred to as rebasing since both are done with the ``git rebase``
command, but there are significant differences between them:

 - Changing the parent (starting) commit upon which a series of patches is
   built.  For example, a rebase operation could take a patch set built on
   the previous kernel release and base it, instead, on the current
   release.  We'll call this operation "reparenting" in the discussion
   below.

 - Changing the history of a set of patches by fixing (or deleting) broken
   commits, adding patches, adding tags to commit changelogs, or changing
   the order in which commits are applied.  In the following text, this
   type of operation will be referred to as "history modification"

The term "rebasing" will be used to refer to both of the above operations.
Used properly, rebasing can yield a cleaner and clearer development
history; used improperly, it can obscure that history and introduce bugs.

There are a few rules of thumb that can help developers to avoid the worst
perils of rebasing:

 - History that has been exposed to the world beyond your private system
   should usually not be changed.  Others may have pulled a copy of your
   tree and built on it; modifying your tree will create pain for them.  If
   work is in need of rebasing, that is usually a sign that it is not yet
   ready to be committed to a public repository.

   That said, there are always exceptions.  Some trees (linux-next being
   a significant example) are frequently rebased by their nature, and
   developers know not to base work on them.  Developers will sometimes
   expose an unstable branch for others to test with or for automated
   testing services.  If you do expose a branch that may be unstable in
   this way, be sure that prospective users know not to base work on it.

 - Do not rebase a branch that contains history created by others.  If you
   have pulled changes from another developer's repository, you are now a
   custodian of their history.  You should not change it.  With few
   exceptions, for example, a broken commit in a tree like this should be
   explicitly reverted rather than disappeared via history modification.

 - Do not reparent a tree without a good reason to do so.  Just being on a
   newer base or avoiding a merge with an upstream repository is not
   generally a good reason.

Annotation

Implementation Notes