Documentation/process/backporting.rst

1 .. SPDX-License-Identifier: GPL-2.0
18 merging branches, or resolving conflicts in their day-to-day work, so
24 This document aims to be a comprehensive, step-by-step guide to
31 in which case you just cherry-pick it directly using
32 ``git cherry-pick``. However, if the patch comes from an email, as it
42 where the patch applies cleanly and *then* cherry-pick it over to your
47 can apply it to the most recent mainline kernel and then cherry-pick it
54 in more unrelated changes in the context of the diff when cherry-picking
57 A good reason to prefer ``git cherry-pick`` over ``git am`` is that git
64 email, you can use ``b4 am`` with the options ``-g``/``--guess-base``
65 and ``-3``/``--prep-3way`` to do some of this automatically (see the
67 article will assume that you are doing a plain ``git cherry-pick``.
69 .. _b4: https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestation
72 Once you have the patch in git, you can go ahead and cherry-pick it into
73 your source tree. Don't forget to cherry-pick with ``-x`` if you want a
89 Uh-oh; the cherry-pick failed with a vaguely threatening message::
104 If your attempted cherry-pick fails with a conflict, git automatically
105 edits the files to include so-called conflict markers showing you where
108 takes into account these other commits.
121 -  `Emacs Ediff mode <https://www.emacswiki.org/emacs/EdiffMode>`__
122 -  `vimdiff/gvimdiff <https://linux.die.net/man/1/vimdiff>`__
123 -  `KDiff3 <http://kdiff3.sourceforge.net/>`__
124 -  `TortoiseMerge <https://tortoisesvn.net/TortoiseMerge.html>`__
125 -  `Meld <https://meldmerge.org/help/>`__
126 -  `P4Merge <https://www.perforce.com/products/helix-core-apps/merge-diff-tool-p4merge>`__
127 -  `Beyond Compare <https://www.scootersoftware.com/>`__
128 -  `IntelliJ <https://www.jetbrains.com/help/idea/resolve-conflicts.html>`__
129 -  `VSCode <https://code.visualstudio.com/docs/editor/versioncontrol>`__
131 To configure git to work with these, see ``git mergetool --help`` or
132 the official `git-mergetool documentation`_.
134 .. _git-mergetool documentation: https://git-scm.com/docs/git-mergetool
137 --------------------
143 simply diverged -- perhaps your older branch had some other backports
147 It's important to always identify the commit or commits that caused the
150 area you're not that familiar with, the changelogs of these commits will
158 conflict -- this is usually sufficient when there aren't a lot of
160 frequently patched. You should run ``git log`` on the range of commits
161 between your currently checked-out branch (``HEAD``) and the parent of
164     git log HEAD..<commit>^ -- <path>
170     git log -L:'\<function\>':<path> HEAD..<commit>^
176      if you use ``-L:thread_stack:kernel/fork.c`` it may only give you
181 Another useful option for ``git log`` is ``-G``, which allows you to
182 filter on certain strings appearing in the diffs of the commits you are
185     git log -G'regex' HEAD..<commit>^ -- <path>
192     git log -G'\->index\>.*='
197 Another way to find prerequisite commits (albeit only the most recent
200 cherry-picking and the file where the conflict appeared, i.e.::
202     git blame <commit>^ -- <path>
204 This command also accepts the ``-L`` argument (for restricting the
208     git blame -L:'\<function\>' <commit>^ -- <path>
214 It might be a good idea to ``git show`` these commits and see if they
216 be more than one of these commits, either because multiple commits
232 incidental -- likewise, a patch that simply renames a function or a
236 patch adding the function should be cherry-picked first.
239 to stop and cherry-pick that instead. If you've already resolved some
243 To abort the current cherry-pick, go ahead and run
244 ``git cherry-pick --abort``, then restart the cherry-picking process
248 ------------------------------
259     this is what's in your current tree before cherry-picking
261     this is what the patch wants it to be after cherry-picking
271      +this is what's in your current tree before cherry-picking
273     + this is what the patch wants it to be after cherry-picking
278 instead of the usual one; this is a so-called "`combined diff`_", here
279 showing the 3-way diff (or diff-of-diffs) between
281 #. the current branch (before cherry-picking) and the current working
283 #. the current branch (before cherry-picking) and the file as it looks
286 .. _combined diff: https://git-scm.com/docs/diff-format#_combined_diff_format
292 3-way combined diffs include all the other changes that happened to the
293 file between your current branch and the branch you are cherry-picking
297 ``git diff HEAD`` (or ``git diff --ours``) which shows only the diff
298 between the current branch before cherry-picking and the current working
304      this is what's in your current tree before cherry-picking
306     +this is what the patch wants it to be after cherry-picking
312 cherry-picked.
322     this is what is in your current tree before cherry-picking
332 changed; i.e., it allows you to compare the before-and-after versions
333 of the file for the commit you are cherry-picking. This allows you to
344 .. _Git 2.35: https://github.blog/2022-01-24-highlights-from-git-2-35/
347 ---------------------------------
352 crashing -- or worse, an undetected security vulnerability.
375 ``git add`` or ``git add -i`` to selectively stage your resolutions to
377 always see what remains to be resolved or ``git diff --cached`` to see
390 renamed file is small, like a one-line change, the easiest thing is to
398 an add-delete pair to be a potential rename)::
400   git cherry-pick -strategy=recursive -Xrename-threshold=30
406 attempt to cherry-pick the patch, rename the file back (``git mv`` and
407 committing again), and finally squash the result using ``git rebase -i``
411 …ase tutorial: https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-re…
414 -------
428 If you cherry-pick a patch that includes a ``goto`` statement (typically
439 ``git diff -W`` and ``git show -W`` (AKA ``--function-context``) when
456 scenario is that a function was renamed -- but that's not always the
464 places exist upstream -- if they don't, it's likely the patch may need
477 ---------
479 Having committed a conflict-free new patch, you can now compare your
484     colordiff -yw -W 200 <(git diff -W <upstream commit>^-) <(git diff -W HEAD^-) | less -SR
488 Here, ``-y`` means to do a side-by-side comparison; ``-w`` ignores
489 whitespace, and ``-W 200`` sets the width of the output (as otherwise it
492 The ``rev^-`` syntax is a handy shorthand for ``rev^..rev``, essentially
494 the official `git rev-parse documentation`_.
496 .. _git rev-parse documentation: https://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand…
498 Again, note the inclusion of ``-W`` for ``git diff``; this ensures that
502 that are different. For example, if an error-handling ``goto`` has
504 show these side-by-side but highlighted in a different color.  Thus, it
514 -------------
529 ---------------
534 file result in no conflicts, no compile-time errors, and runtime errors
541 cherry-pick the second patch, have no conflicts, and believe that
555 As the stable maintainers try to cherry-pick mainline fixes onto their
558 <https://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/>.
559 These emails typically include the exact steps you need to cherry-pick
571   Signed-off-by: <your name and email>
580 ``git send-email --subject-prefix='PATCH 6.1.y'``), but you can also put
581 it in the Signed-off-by:-area or below the ``---`` line.