Documentation/maintainer/rebasing-and-merging.rst

1 .. SPDX-License-Identifier: GPL-2.0
7 Maintaining a subsystem, as a general rule, requires a familiarity with the
8 Git source-code management system.  Git is a powerful tool with a lot of
19 maintainers result from a desire to avoid merges, while others come from
20 merging a little too often.
25 "Rebasing" is the process of changing the history of a series of commits
26 within a repository.  There are two different types of operations that are
30  - Changing the parent (starting) commit upon which a series of patches is
31    built.  For example, a rebase operation could take a patch set built on
36  - Changing the history of a set of patches by fixing (or deleting) broken
42 Used properly, rebasing can yield a cleaner and clearer development
45 There are a few rules of thumb that can help developers to avoid the worst
48  - History that has been exposed to the world beyond your private system
49    should usually not be changed.  Others may have pulled a copy of your
51    work is in need of rebasing, that is usually a sign that it is not yet
52    ready to be committed to a public repository.
54    That said, there are always exceptions.  Some trees (linux-next being
55    a significant example) are frequently rebased by their nature, and
58    testing services.  If you do expose a branch that may be unstable in
61  - Do not rebase a branch that contains history created by others.  If you
62    have pulled changes from another developer's repository, you are now a
64    exceptions, for example, a broken commit in a tree like this should be
67  - Do not reparent a tree without a good reason to do so.  Just being on a
68    newer base or avoiding a merge with an upstream repository is not
69    generally a good reason.
71  - If you must reparent a repository, do not pick some random kernel commit
72    as the new base.  The kernel is often in a relatively unstable state
74    increases the chances of running into surprising bugs.  When a patch
75    series must move to a new base, pick a stable point (such as one of
76    the -rc releases) to move to.
78  - Realize that reparenting a patch series (or making significant history
80    likely, invalidates much of the testing that was done.  A reparented
81    patch series should, as a general rule, be treated like new code and
84 A frequent cause of merge-window trouble is when Linus is presented with a
85 patch series that has clearly been reparented, often to a random commit,
86 shortly before the pull request was sent.  The chances of such a series
87 having been adequately tested are relatively low - as are the chances of
90 If, instead, rebasing is limited to private trees, commits are based on a
91 well-known starting point, and they are well tested, the potential for
97 Merging is a common operation in the kernel development process; the 5.1
98 development cycle included 1,126 merge commits - nearly 9% of the total.
106 is not such a project; any rebasing of branches to avoid merges will, most
110 from lower-level subsystem trees and from others, either sibling trees or
113 Merging from lower-level trees
114 ------------------------------
117 lower-level maintainers sending pull requests to the higher levels.  Acting
118 on such a pull request will almost certainly generate a merge commit; that
120 the --no-ff flag to force the addition of a merge commit in the rare cases
123 merge, say *why* the merge is being done.  For a lower-level tree, "why" is
124 usually a summary of the changes that will come with that pull.
129 process as a whole.
136 --------------------------------------
139 trees tend to be a red flag when it comes time to push a branch upstream.
141 there's a good chance that a subsequent pull request will be rejected.
143 It is natural to want to merge the master branch into a repository; this
144 type of merge is often called a "back merge".  Back merges can help to make
146 gives a warm, fuzzy feeling of being up-to-date.  But this temptation
155 a well-managed branch.
159 merge to a well-known stable point, rather than to some random commit.
160 Even then, you should not back merge a tree above your immediate upstream
161 tree; if a higher-level back merge is really required, the upstream tree
164 One of the most frequent causes of merge-related trouble is when a
166 before sending a pull request.  Again, this temptation is easy enough to
170 him know where potential problem areas are.  He does a lot of merges (382
172 resolution - often better than the developers involved.
174 So what should a maintainer do when there is a conflict between their
178 especially difficult conflicts, create and push a *separate* branch to show
182 Even in the absence of known conflicts, doing a test merge before sending a
183 pull request is a good idea.  It may alert you to problems that you somehow
184 didn't see from linux-next and helps to understand exactly what you are
189 sometimes a cross-merge with another tree is the best way to resolve them;
191 merge has been done.  Take a moment to do it right; people will read those
194 Often, though, dependency issues indicate that a change of approach is
195 needed.  Merging another subsystem tree to resolve a dependency risks
200 creating a topic branch dedicated to the prerequisite commits that can be
211 in the tree.  As always, such a merge should pick a well-known release
212 point rather than some random spot.  If your upstream-bound branch has
214 forward with a command like::
216   git merge --ff-only v5.2-rc1
219 be situations that call out for a different solution, and these guidelines