1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===================================
4 Backporting and conflict resolution
5 ===================================
6
7 :Author: Vegard Nossum <vegard.nossum@oracle.co
8
9 .. contents::
10 :local:
11 :depth: 3
12 :backlinks: none
13
14 Introduction
15 ============
16
17 Some developers may never really have to deal
18 merging branches, or resolving conflicts in th
19 when a merge conflict does pop up, it can be d
20 resolving conflicts is a skill like any other,
21 techniques you can use to make the process smo
22 confidence in the result.
23
24 This document aims to be a comprehensive, step
25 backporting and conflict resolution.
26
27 Applying the patch to a tree
28 ============================
29
30 Sometimes the patch you are backporting alread
31 in which case you just cherry-pick it directly
32 ``git cherry-pick``. However, if the patch com
33 often does for the Linux kernel, you will need
34 using ``git am``.
35
36 If you've ever used ``git am``, you probably a
37 quite picky about the patch applying perfectly
38 fact, you've probably had nightmares about ``.
39 edit the patch to make it apply.
40
41 It is strongly recommended to instead find an
42 where the patch applies cleanly and *then* che
43 destination tree, as this will make git output
44 you resolve conflicts with the help of git and
45 resolution tools you might prefer to use. For
46 apply a patch that just arrived on LKML to an
47 can apply it to the most recent mainline kerne
48 to your older stable branch.
49
50 It's generally better to use the exact same ba
51 was generated from, but it doesn't really matt
52 applies cleanly and isn't too far from the ori
53 problem with applying the patch to the "wrong"
54 in more unrelated changes in the context of th
55 it to the older branch.
56
57 A good reason to prefer ``git cherry-pick`` ov
58 knows the precise history of an existing commi
59 code has moved around and changed the line num
60 it less likely to apply the patch to the wrong
61 in silent mistakes or messy conflicts).
62
63 If you are using `b4`_. and you are applying t
64 email, you can use ``b4 am`` with the options
65 and ``-3``/``--prep-3way`` to do some of this
66 `b4 presentation`_ for more information). Howe
67 article will assume that you are doing a plain
68
69 .. _b4: https://people.kernel.org/monsieuricon
70 .. _b4 presentation: https://youtu.be/mF10hgVI
71
72 Once you have the patch in git, you can go ahe
73 your source tree. Don't forget to cherry-pick
74 written record of where the patch came from!
75
76 Note that if you are submitting a patch for st
77 slightly different; the first line after the s
78 either::
79
80 commit <upstream commit> upstream
81
82 or::
83
84 [ Upstream commit <upstream commit> ]
85
86 Resolving conflicts
87 ===================
88
89 Uh-oh; the cherry-pick failed with a vaguely t
90
91 CONFLICT (content): Merge conflict
92
93 What to do now?
94
95 In general, conflicts appear when the context
96 lines being changed and/or the lines surroundi
97 match what's in the tree you are trying to app
98
99 For backports, what likely happened was that t
100 backporting from contains patches not in the b
101 to. However, the reverse is also possible. In
102 conflict that needs to be resolved.
103
104 If your attempted cherry-pick fails with a con
105 edits the files to include so-called conflict
106 the conflict is and how the two branches have
107 conflict typically means editing the end resul
108 takes into account these other commits.
109
110 Resolving the conflict can be done either by h
111 editor or using a dedicated conflict resolutio
112
113 Many people prefer to use their regular text e
114 conflict directly, as it may be easier to unde
115 and to control the final result. There are def
116 each method, and sometimes there's value in us
117
118 We will not cover using dedicated merge tools
119 pointers to various tools that you could use:
120
121 - `Emacs Ediff mode <https://www.emacswiki.or
122 - `vimdiff/gvimdiff <https://linux.die.net/ma
123 - `KDiff3 <http://kdiff3.sourceforge.net/>`__
124 - `TortoiseMerge <https://tortoisesvn.net/Tor
125 - `Meld <https://meldmerge.org/help/>`__
126 - `P4Merge <https://www.perforce.com/products
127 - `Beyond Compare <https://www.scootersoftwar
128 - `IntelliJ <https://www.jetbrains.com/help/i
129 - `VSCode <https://code.visualstudio.com/docs
130
131 To configure git to work with these, see ``git
132 the official `git-mergetool documentation`_.
133
134 .. _git-mergetool documentation: https://git-s
135
136 Prerequisite patches
137 --------------------
138
139 Most conflicts happen because the branch you a
140 missing some patches compared to the branch yo
141 In the more general case (such as merging two
142 development could have happened on either bran
143 simply diverged -- perhaps your older branch h
144 applied to it that themselves needed conflict
145 divergence.
146
147 It's important to always identify the commit o
148 conflict, as otherwise you cannot be confident
149 your resolution. As an added bonus, especially
150 area you're not that familiar with, the change
151 often give you the context to understand the c
152 or pitfalls with your conflict resolution.
153
154 git log
155 ~~~~~~~
156
157 A good first step is to look at ``git log`` fo
158 conflict -- this is usually sufficient when th
159 patches to the file, but may get confusing if
160 frequently patched. You should run ``git log``
161 between your currently checked-out branch (``H
162 the patch you are picking (``<commit>``), i.e.
163
164 git log HEAD..<commit>^ -- <path>
165
166 Even better, if you want to restrict this outp
167 (because that's where the conflict appears), y
168 syntax::
169
170 git log -L:'\<function\>':<path> HEAD..<co
171
172 .. note::
173 The ``\<`` and ``\>`` around the function
174 matches are anchored on a word boundary.
175 part is actually a regex and git only fol
176 if you use ``-L:thread_stack:kernel/fork.
177 results for the function ``try_release_th
178 though there are many other functions in
179 string ``thread_stack`` in their names.
180
181 Another useful option for ``git log`` is ``-G`
182 filter on certain strings appearing in the dif
183 listing::
184
185 git log -G'regex' HEAD..<commit>^ -- <path
186
187 This can also be a handy way to quickly find w
188 function call or a variable) was changed, adde
189 string is a regular expression, which means yo
190 for more specific things like assignments to a
191
192 git log -G'\->index\>.*='
193
194 git blame
195 ~~~~~~~~~
196
197 Another way to find prerequisite commits (albe
198 one for a given conflict) is to run ``git blam
199 need to run it against the parent commit of th
200 cherry-picking and the file where the conflict
201
202 git blame <commit>^ -- <path>
203
204 This command also accepts the ``-L`` argument
205 output to a single function), but in this case
206 at the end of the command as usual::
207
208 git blame -L:'\<function\>' <commit>^ -- <
209
210 Navigate to the place where the conflict occur
211 the blame output is the commit ID of the patch
212 of code.
213
214 It might be a good idea to ``git show`` these
215 look like they might be the source of the conf
216 be more than one of these commits, either beca
217 changed different lines of the same conflict a
218 subsequent patches changed the same line (or l
219 the latter case, you may have to run ``git bla
220 older version of the file to look at in order
221 the history of the file.
222
223 Prerequisite vs. incidental patches
224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225
226 Having found the patch that caused the conflic
227 whether it is a prerequisite for the patch you
228 whether it is just incidental and can be skipp
229 would be one that touches the same code as the
230 backporting, but does not change the semantics
231 material way. For example, a whitespace cleanu
232 incidental -- likewise, a patch that simply re
233 variable would be incidental as well. On the o
234 being changed does not even exist in your curr
235 not be incidental at all and you need to caref
236 patch adding the function should be cherry-pic
237
238 If you find that there is a necessary prerequi
239 to stop and cherry-pick that instead. If you'v
240 conflicts in a different file and don't want t
241 create a temporary copy of that file.
242
243 To abort the current cherry-pick, go ahead and
244 ``git cherry-pick --abort``, then restart the
245 with the commit ID of the prerequisite patch i
246
247 Understanding conflict markers
248 ------------------------------
249
250 Combined diffs
251 ~~~~~~~~~~~~~~
252
253 Let's say you've decided against picking (or r
254 patches and you just want to resolve the confl
255 inserted conflict markers into your file. Out
256 something like::
257
258 <<<<<<< HEAD
259 this is what's in your current tree before
260 =======
261 this is what the patch wants it to be afte
262 >>>>>>> <commit>... title
263
264 This is what you would see if you opened the f
265 However, if you were to run ``git diff`` witho
266 output would look something like this::
267
268 $ git diff
269 [...]
270 ++<<<<<<<< HEAD
271 +this is what's in your current tree befo
272 ++========
273 + this is what the patch wants it to be af
274 ++>>>>>>>> <commit>... title
275
276 When you are resolving a conflict, the behavio
277 from its normal behavior. Notice the two colum
278 instead of the usual one; this is a so-called
279 showing the 3-way diff (or diff-of-diffs) betw
280
281 #. the current branch (before cherry-picking)
282 directory, and
283 #. the current branch (before cherry-picking)
284 after the original patch has been applied.
285
286 .. _combined diff: https://git-scm.com/docs/di
287
288
289 Better diffs
290 ~~~~~~~~~~~~
291
292 3-way combined diffs include all the other cha
293 file between your current branch and the branc
294 from. While this is useful for spotting other
295 take into account, this also makes the output
296 intimidating and difficult to read. You may in
297 ``git diff HEAD`` (or ``git diff --ours``) whi
298 between the current branch before cherry-picki
299 directory. It looks like this::
300
301 $ git diff HEAD
302 [...]
303 +<<<<<<<< HEAD
304 this is what's in your current tree befor
305 +========
306 +this is what the patch wants it to be aft
307 +>>>>>>>> <commit>... title
308
309 As you can see, this reads just like any other
310 which lines are in the current branch and whic
311 because they are part of the merge conflict or
312 cherry-picked.
313
314 Merge styles and diff3
315 ~~~~~~~~~~~~~~~~~~~~~~
316
317 The default conflict marker style shown above
318 style. There is also another style available,
319 style, which looks like this::
320
321 <<<<<<< HEAD
322 this is what is in your current tree befor
323 ||||||| parent of <commit> (title)
324 this is what the patch expected to find th
325 =======
326 this is what the patch wants it to be afte
327 >>>>>>> <commit> (title)
328
329 As you can see, this has 3 parts instead of 2,
330 expected to find there but didn't. It is *high
331 this conflict style as it makes it much cleare
332 changed; i.e., it allows you to compare the be
333 of the file for the commit you are cherry-pick
334 make better decisions about how to resolve the
335
336 To change conflict marker styles, you can use
337
338 git config merge.conflictStyle diff3
339
340 There is a third option, ``zdiff3``, introduce
341 which has the same 3 sections as ``diff3``, bu
342 been trimmed off, making the conflict area sma
343
344 .. _Git 2.35: https://github.blog/2022-01-24-h
345
346 Iterating on conflict resolutions
347 ---------------------------------
348
349 The first step in any conflict resolution proc
350 patch you are backporting. For the Linux kerne
351 important, since an incorrect change can lead
352 crashing -- or worse, an undetected security v
353
354 Understanding the patch can be easy or difficu
355 itself, the changelog, and your familiarity wi
356 However, a good question for every change (or
357 might be: "Why is this hunk in the patch?" The
358 questions will inform your conflict resolution
359
360 Resolution process
361 ~~~~~~~~~~~~~~~~~~
362
363 Sometimes the easiest thing to do is to just r
364 part of the conflict, leaving the file essenti
365 the changes by hand. Perhaps the patch is chan
366 argument from ``0`` to ``1`` while a conflicti
367 entirely new (and insignificant) parameter to
368 list; in that case, it's easy enough to change
369 to ``1`` by hand and leave the rest of the arg
370 technique of manually applying changes is most
371 pulled in a lot of unrelated context that you
372 about.
373
374 For particularly nasty conflicts with many con
375 ``git add`` or ``git add -i`` to selectively s
376 get them out of the way; this also lets you us
377 always see what remains to be resolved or ``gi
378 what your patch looks like so far.
379
380 Dealing with file renames
381 ~~~~~~~~~~~~~~~~~~~~~~~~~
382
383 One of the most annoying things that can happe
384 patch is discovering that one of the files bei
385 renamed, as that typically means git won't eve
386 but will just throw up its hands and say (para
387 You do the work..."
388
389 There are generally a few ways to deal with th
390 renamed file is small, like a one-line change,
391 just go ahead and apply the change by hand and
392 other hand, if the change is big or complicate
393 want to do it by hand.
394
395 As a first pass, you can try something like th
396 rename detection threshold to 30% (by default,
397 that two files need to have at least 50% in co
398 an add-delete pair to be a potential rename)::
399
400 git cherry-pick -strategy=recursive -Xrename
401
402 Sometimes the right thing to do will be to als
403 did the rename, but that's definitely not the
404 what you can do is to temporarily rename the f
405 backporting to (using ``git mv`` and committin
406 attempt to cherry-pick the patch, rename the f
407 committing again), and finally squash the resu
408 (see the `rebase tutorial`_) so it appears as
409 are done.
410
411 .. _rebase tutorial: https://medium.com/@slamf
412
413 Gotchas
414 -------
415
416 Function arguments
417 ~~~~~~~~~~~~~~~~~~
418
419 Pay attention to changing function arguments!
420 details and think that two lines are the same
421 in some small detail like which variable was p
422 (especially if the two variables are both a si
423 the same, like i and j).
424
425 Error handling
426 ~~~~~~~~~~~~~~
427
428 If you cherry-pick a patch that includes a ``g
429 for error handling), it is absolutely imperati
430 the target label is still correct in the branc
431 The same goes for added ``return``, ``break``,
432 statements.
433
434 Error handling is typically located at the bot
435 may not be part of the conflict even though co
436 other patches.
437
438 A good way to ensure that you review the error
439 ``git diff -W`` and ``git show -W`` (AKA ``--f
440 inspecting your changes. For C code, this wil
441 function that's being changed in a patch. One
442 go wrong during backports is that something el
443 on either of the branches that you're backport
444 including the whole function in the diff you g
445 more easily spot problems that might otherwise
446
447 Refactored code
448 ~~~~~~~~~~~~~~~
449
450 Something that happens quite often is that cod
451 "factoring out" a common code sequence or patt
452 function. When backporting patches to an area
453 has taken place, you effectively need to do th
454 backporting: a patch to a single location may
455 multiple locations in the backported version.
456 scenario is that a function was renamed -- but
457 case.)
458
459 To avoid incomplete backports, it's worth tryi
460 patch fixes a bug that appears in more than on
461 this would be to use ``git grep``. (This is ac
462 in general, not just for backports.) If you do
463 of fix would apply to other places, it's also
464 places exist upstream -- if they don't, it's l
465 to be adjusted. ``git log`` is your friend to
466 to these areas as ``git blame`` won't show you
467 removed.
468
469 If you do find other instances of the same pat
470 and you're not sure whether it's also a bug, i
471 patch author. It's not uncommon to find new bu
472
473 Verifying the result
474 ====================
475
476 colordiff
477 ---------
478
479 Having committed a conflict-free new patch, yo
480 patch to the original patch. It is highly reco
481 tool such as `colordiff`_ that can show two fi
482 them according to the changes between them::
483
484 colordiff -yw -W 200 <(git diff -W <upstre
485
486 .. _colordiff: https://www.colordiff.org/
487
488 Here, ``-y`` means to do a side-by-side compar
489 whitespace, and ``-W 200`` sets the width of t
490 will use 130 by default, which is often a bit
491
492 The ``rev^-`` syntax is a handy shorthand for
493 giving you just the diff for that single commi
494 the official `git rev-parse documentation`_.
495
496 .. _git rev-parse documentation: https://git-s
497
498 Again, note the inclusion of ``-W`` for ``git
499 you will see the full function for any functio
500
501 One incredibly important thing that colordiff
502 that are different. For example, if an error-h
503 changed labels between the original and backpo
504 show these side-by-side but highlighted in a d
505 is easy to see that the two ``goto`` statement
506 labels. Likewise, lines that were not modified
507 differ in the context will also be highlighted
508 a manual inspection.
509
510 Of course, this is just a visual inspection; t
511 and running the patched kernel (or program).
512
513 Build testing
514 -------------
515
516 We won't cover runtime testing here, but it ca
517 just the files touched by the patch as a quick
518 Linux kernel you can build single files like t
519 ``.config`` and build environment set up corre
520
521 make path/to/file.o
522
523 Note that this won't discover linker errors, s
524 full build after verifying that the single fil
525 the single file first you can avoid having to
526 case* there are compiler errors in any of the
527
528 Runtime testing
529 ---------------
530
531 Even a successful build or boot test is not ne
532 out a missing dependency somewhere. Even thoug
533 there could be code changes where two independ
534 file result in no conflicts, no compile-time e
535 only in exceptional cases.
536
537 One concrete example of this was a pair of pat
538 entry code where the first patch saved/restore
539 patch made use of the same register somewhere
540 sequence. Since there was no overlap between t
541 cherry-pick the second patch, have no conflict
542 everything was fine, when in fact the code was
543 unsaved register.
544
545 Although the vast majority of errors will be c
546 or by superficially exercising the code, the o
547 a backport is to review the final patch with t
548 as you would (or should) give to any other pat
549 regression tests or other types of automatic t
550 the confidence in the correctness of a backpor
551
552 Submitting backports to stable
553 ==============================
554
555 As the stable maintainers try to cherry-pick m
556 stable kernels, they may send out emails askin
557 encountering conflicts, see e.g.
558 <https://lore.kernel.org/stable/2023101528-jawe
559 These emails typically include the exact steps
560 the patch to the correct tree and submit the p
561
562 One thing to make sure is that your changelog
563 format::
564
565 <original patch title>
566
567 [ Upstream commit <mainline rev> ]
568
569 <rest of the original changelog>
570 [ <summary of the conflicts and their resolu
571 Signed-off-by: <your name and email>
572
573 The "Upstream commit" line is sometimes slight
574 the stable version. Older version used this fo
575
576 commit <mainline rev> upstream.
577
578 It is most common to indicate the kernel versi
579 in the email subject line (using e.g.
580 ``git send-email --subject-prefix='PATCH 6.1.y
581 it in the Signed-off-by:-area or below the ``-
582
583 The stable maintainers expect separate submiss
584 stable version, and each submission should als
585
586 A few final words of advice
587 ===========================
588
589 1) Approach the backporting process with humil
590 2) Understand the patch you are backporting; t
591 the changelog and the code.
592 3) Be honest about your confidence in the resu
593 patch.
594 4) Ask relevant maintainers for explicit acks.
595
596 Examples
597 ========
598
599 The above shows roughly the idealized process
600 For a more concrete example, see this video tu
601 are backported from mainline to stable:
602 `Backporting Linux Kernel Patches`_.
603
604 .. _Backporting Linux Kernel Patches: https://
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.