sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget'/translations/zh_CN/process/backportingmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/zh_TW/process/backportingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/it_IT/process/backportingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ja_JP/process/backportingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ko_KR/process/backportingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/pt_BR/process/backportingmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/sp_SP/process/backportingmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhA/var/lib/git/docbuild/linux/Documentation/process/backporting.rsthKubhsection)}(hhh](htitle)}(h#Backporting and conflict resolutionh]h#Backporting and conflict resolution}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh field_list)}(hhh]hfield)}(hhh](h field_name)}(hAuthorh]hAuthor}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhKubh field_body)}(h)Vegard Nossum h]h paragraph)}(h(Vegard Nossum h](hVegard Nossum <}(hhhhhNhNubh reference)}(hvegard.nossum@oracle.comh]hvegard.nossum@oracle.com}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurimailto:vegard.nossum@oracle.comuh1jhhubh>}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubhtopic)}(hhh]h bullet_list)}(hhh](h list_item)}(hhh]h)}(hhh]j)}(hhh]h Introduction}(hjGhhhNhNubah}(h]id2ah ]h"]h$]h&]refid introductionuh1jhjDubah}(h]h ]h"]h$]h&]uh1hhjAubah}(h]h ]h"]h$]h&]uh1j?hj<ubj@)}(hhh]h)}(hhh]j)}(hhh]hApplying the patch to a tree}(hjihhhNhNubah}(h]id3ah ]h"]h$]h&]refidapplying-the-patch-to-a-treeuh1jhjfubah}(h]h ]h"]h$]h&]uh1hhjcubah}(h]h ]h"]h$]h&]uh1j?hj<ubj@)}(hhh](h)}(hhh]j)}(hhh]hResolving conflicts}(hjhhhNhNubah}(h]id4ah ]h"]h$]h&]refidresolving-conflictsuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubj;)}(hhh](j@)}(hhh](h)}(hhh]j)}(hhh]hPrerequisite patches}(hjhhhNhNubah}(h]id5ah ]h"]h$]h&]refidprerequisite-patchesuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubj;)}(hhh](j@)}(hhh]h)}(hhh]j)}(hhh]hgit log}(hjhhhNhNubah}(h]id6ah ]h"]h$]h&]refidgit-loguh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh]h)}(hhh]j)}(hhh]h git blame}(hjhhhNhNubah}(h]id7ah ]h"]h$]h&]refid git-blameuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh]h)}(hhh]j)}(hhh]h#Prerequisite vs. incidental patches}(hj hhhNhNubah}(h]id8ah ]h"]h$]h&]refid"prerequisite-vs-incidental-patchesuh1jhj ubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjubeh}(h]h ]h"]h$]h&]uh1j:hjubeh}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh](h)}(hhh]j)}(hhh]hUnderstanding conflict markers}(hj;hhhNhNubah}(h]id9ah ]h"]h$]h&]refidunderstanding-conflict-markersuh1jhj8ubah}(h]h ]h"]h$]h&]uh1hhj5ubj;)}(hhh](j@)}(hhh]h)}(hhh]j)}(hhh]hCombined diffs}(hjZhhhNhNubah}(h]id10ah ]h"]h$]h&]refidcombined-diffsuh1jhjWubah}(h]h ]h"]h$]h&]uh1hhjTubah}(h]h ]h"]h$]h&]uh1j?hjQubj@)}(hhh]h)}(hhh]j)}(hhh]h Better diffs}(hj|hhhNhNubah}(h]id11ah ]h"]h$]h&]refid better-diffsuh1jhjyubah}(h]h ]h"]h$]h&]uh1hhjvubah}(h]h ]h"]h$]h&]uh1j?hjQubj@)}(hhh]h)}(hhh]j)}(hhh]hMerge styles and diff3}(hjhhhNhNubah}(h]id12ah ]h"]h$]h&]refidmerge-styles-and-diff3uh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjQubeh}(h]h ]h"]h$]h&]uh1j:hj5ubeh}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh](h)}(hhh]j)}(hhh]h!Iterating on conflict resolutions}(hjhhhNhNubah}(h]id13ah ]h"]h$]h&]refid!iterating-on-conflict-resolutionsuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubj;)}(hhh](j@)}(hhh]h)}(hhh]j)}(hhh]hResolution process}(hjhhhNhNubah}(h]id14ah ]h"]h$]h&]refidresolution-processuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh]h)}(hhh]j)}(hhh]hDealing with file renames}(hj hhhNhNubah}(h]id15ah ]h"]h$]h&]refiddealing-with-file-renamesuh1jhj ubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjubeh}(h]h ]h"]h$]h&]uh1j:hjubeh}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh](h)}(hhh]j)}(hhh]hGotchas}(hj;hhhNhNubah}(h]id16ah ]h"]h$]h&]refidgotchasuh1jhj8ubah}(h]h ]h"]h$]h&]uh1hhj5ubj;)}(hhh](j@)}(hhh]h)}(hhh]j)}(hhh]hFunction arguments}(hjZhhhNhNubah}(h]id17ah ]h"]h$]h&]refidfunction-argumentsuh1jhjWubah}(h]h ]h"]h$]h&]uh1hhjTubah}(h]h ]h"]h$]h&]uh1j?hjQubj@)}(hhh]h)}(hhh]j)}(hhh]hError handling}(hj|hhhNhNubah}(h]id18ah ]h"]h$]h&]refiderror-handlinguh1jhjyubah}(h]h ]h"]h$]h&]uh1hhjvubah}(h]h ]h"]h$]h&]uh1j?hjQubj@)}(hhh]h)}(hhh]j)}(hhh]hRefactored code}(hjhhhNhNubah}(h]id19ah ]h"]h$]h&]refidrefactored-codeuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjQubeh}(h]h ]h"]h$]h&]uh1j:hj5ubeh}(h]h ]h"]h$]h&]uh1j?hjubeh}(h]h ]h"]h$]h&]uh1j:hjubeh}(h]h ]h"]h$]h&]uh1j?hj<ubj@)}(hhh](h)}(hhh]j)}(hhh]hVerifying the result}(hjhhhNhNubah}(h]id20ah ]h"]h$]h&]refidverifying-the-resultuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubj;)}(hhh](j@)}(hhh]h)}(hhh]j)}(hhh]h colordiff}(hjhhhNhNubah}(h]id21ah ]h"]h$]h&]refid colordiffuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh]h)}(hhh]j)}(hhh]h Build testing}(hjhhhNhNubah}(h]id22ah ]h"]h$]h&]refid build-testinguh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hjubj@)}(hhh]h)}(hhh]j)}(hhh]hRuntime testing}(hj;hhhNhNubah}(h]id23ah ]h"]h$]h&]refidruntime-testinguh1jhj8ubah}(h]h ]h"]h$]h&]uh1hhj5ubah}(h]h ]h"]h$]h&]uh1j?hjubeh}(h]h ]h"]h$]h&]uh1j:hjubeh}(h]h ]h"]h$]h&]uh1j?hj<ubj@)}(hhh]h)}(hhh]j)}(hhh]hSubmitting backports to stable}(hjihhhNhNubah}(h]id24ah ]h"]h$]h&]refidsubmitting-backports-to-stableuh1jhjfubah}(h]h ]h"]h$]h&]uh1hhjcubah}(h]h ]h"]h$]h&]uh1j?hj<ubj@)}(hhh]h)}(hhh]j)}(hhh]hA few final words of advice}(hjhhhNhNubah}(h]id25ah ]h"]h$]h&]refida-few-final-words-of-adviceuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hj<ubj@)}(hhh]h)}(hhh]j)}(hhh]hExamples}(hjhhhNhNubah}(h]id26ah ]h"]h$]h&]refidexamplesuh1jhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j?hj<ubeh}(h]h ]h"]h$]h&]uh1j:hj7hhhNhNubah}(h]contentsah ](contentslocaleh"]contentsah$]h&]uh1j5hhhK hhhhubh)}(hhh](h)}(h Introductionh]h Introduction}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXvSome developers may never really have to deal with backporting patches, merging branches, or resolving conflicts in their day-to-day work, so when a merge conflict does pop up, it can be daunting. Luckily, resolving conflicts is a skill like any other, and there are many useful techniques you can use to make the process smoother and increase your confidence in the result.h]hXvSome developers may never really have to deal with backporting patches, merging branches, or resolving conflicts in their day-to-day work, so when a merge conflict does pop up, it can be daunting. Luckily, resolving conflicts is a skill like any other, and there are many useful techniques you can use to make the process smoother and increase your confidence in the result.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hdThis document aims to be a comprehensive, step-by-step guide to backporting and conflict resolution.h]hdThis document aims to be a comprehensive, step-by-step guide to backporting and conflict resolution.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]jVah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hApplying the patch to a treeh]hApplying the patch to a tree}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hXSometimes the patch you are backporting already exists as a git commit, in which case you just cherry-pick it directly using ``git cherry-pick``. However, if the patch comes from an email, as it often does for the Linux kernel, you will need to apply it to a tree using ``git am``.h](h}Sometimes the patch you are backporting already exists as a git commit, in which case you just cherry-pick it directly using }(hjhhhNhNubhliteral)}(h``git cherry-pick``h]hgit cherry-pick}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh~. However, if the patch comes from an email, as it often does for the Linux kernel, you will need to apply it to a tree using }(hjhhhNhNubj')}(h ``git am``h]hgit am}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hIf you've ever used ``git am``, you probably already know that it is quite picky about the patch applying perfectly to your source tree. In fact, you've probably had nightmares about ``.rej`` files and trying to edit the patch to make it apply.h](hIf you’ve ever used }(hjRhhhNhNubj')}(h ``git am``h]hgit am}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjRubh, you probably already know that it is quite picky about the patch applying perfectly to your source tree. In fact, you’ve probably had nightmares about }(hjRhhhNhNubj')}(h``.rej``h]h.rej}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjRubh5 files and trying to edit the patch to make it apply.}(hjRhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK$hj hhubh)}(hX It is strongly recommended to instead find an appropriate base version where the patch applies cleanly and *then* cherry-pick it over to your destination tree, as this will make git output conflict markers and let you resolve conflicts with the help of git and any other conflict resolution tools you might prefer to use. For example, if you want to apply a patch that just arrived on LKML to an older stable kernel, you can apply it to the most recent mainline kernel and then cherry-pick it to your older stable branch.h](hkIt is strongly recommended to instead find an appropriate base version where the patch applies cleanly and }(hjhhhNhNubhemphasis)}(h*then*h]hthen}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX cherry-pick it over to your destination tree, as this will make git output conflict markers and let you resolve conflicts with the help of git and any other conflict resolution tools you might prefer to use. For example, if you want to apply a patch that just arrived on LKML to an older stable kernel, you can apply it to the most recent mainline kernel and then cherry-pick it to your older stable branch.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK)hj hhubh)}(hXzIt's generally better to use the exact same base as the one the patch was generated from, but it doesn't really matter that much as long as it applies cleanly and isn't too far from the original base. The only problem with applying the patch to the "wrong" base is that it may pull in more unrelated changes in the context of the diff when cherry-picking it to the older branch.h]hXIt’s generally better to use the exact same base as the one the patch was generated from, but it doesn’t really matter that much as long as it applies cleanly and isn’t too far from the original base. The only problem with applying the patch to the “wrong” base is that it may pull in more unrelated changes in the context of the diff when cherry-picking it to the older branch.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK2hj hhubh)}(hXCA good reason to prefer ``git cherry-pick`` over ``git am`` is that git knows the precise history of an existing commit, so it will know when code has moved around and changed the line numbers; this in turn makes it less likely to apply the patch to the wrong place (which can result in silent mistakes or messy conflicts).h](hA good reason to prefer }(hjhhhNhNubj')}(h``git cherry-pick``h]hgit cherry-pick}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh over }(hjhhhNhNubj')}(h ``git am``h]hgit am}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubhX is that git knows the precise history of an existing commit, so it will know when code has moved around and changed the line numbers; this in turn makes it less likely to apply the patch to the wrong place (which can result in silent mistakes or messy conflicts).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK9hj hhubh)}(hXZIf you are using `b4`_. and you are applying the patch directly from an email, you can use ``b4 am`` with the options ``-g``/``--guess-base`` and ``-3``/``--prep-3way`` to do some of this automatically (see the `b4 presentation`_ for more information). However, the rest of this article will assume that you are doing a plain ``git cherry-pick``.h](hIf you are using }(hjhhhNhNubj)}(h`b4`_h]hb4}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameb4refuriKhttps://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestationuh1jhjresolvedKubhE. and you are applying the patch directly from an email, you can use }(hjhhhNhNubj')}(h ``b4 am``h]hb4 am}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh with the options }(hjhhhNhNubj')}(h``-g``h]h-g}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh/}(hjhhhNhNubj')}(h``--guess-base``h]h --guess-base}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh and }(hjhhhNhNubj')}(h``-3``h]h-3}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh/}hjsbj')}(h``--prep-3way``h]h --prep-3way}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh+ to do some of this automatically (see the }(hjhhhNhNubj)}(h`b4 presentation`_h]hb4 presentation}(hj_hhhNhNubah}(h]h ]h"]h$]h&]nameb4 presentationj#https://youtu.be/mF10hgVIx9o?t=2996uh1jhjjKubha for more information). However, the rest of this article will assume that you are doing a plain }(hjhhhNhNubj')}(h``git cherry-pick``h]hgit cherry-pick}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK?hj hhubhtarget)}(hS.. _b4: https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestationh]h}(h]b4ah ]h"]b4ah$]h&]jjuh1jhKEhj hhhhnj referencedKubj)}(h8.. _b4 presentation: https://youtu.be/mF10hgVIx9o?t=2996h]h}(h]b4-presentationah ]h"]b4 presentationah$]h&]jjouh1jhKFhj hhhhjKubh)}(hOnce you have the patch in git, you can go ahead and cherry-pick it into your source tree. Don't forget to cherry-pick with ``-x`` if you want a written record of where the patch came from!h](h~Once you have the patch in git, you can go ahead and cherry-pick it into your source tree. Don’t forget to cherry-pick with }(hjhhhNhNubj')}(h``-x``h]h-x}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh; if you want a written record of where the patch came from!}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKHhj hhubh)}(hNote that if you are submitting a patch for stable, the format is slightly different; the first line after the subject line needs to be either::h]hNote that if you are submitting a patch for stable, the format is slightly different; the first line after the subject line needs to be either:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhj hhubh literal_block)}(h!commit upstreamh]h!commit upstream}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKPhj hhubh)}(hor::h]hor:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKRhj hhubj)}(h%[ Upstream commit ]h]h%[ Upstream commit ]}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKThj hhubeh}(h]jxah ]h"]applying the patch to a treeah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hResolving conflictsh]hResolving conflicts}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKWubh)}(hBUh-oh; the cherry-pick failed with a vaguely threatening message::h]hAUh-oh; the cherry-pick failed with a vaguely threatening message:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKYhjhhubj)}(h"CONFLICT (content): Merge conflicth]h"CONFLICT (content): Merge conflict}hj'sbah}(h]h ]h"]h$]h&]hhuh1jhhhK[hjhhubh)}(hWhat to do now?h]hWhat to do now?}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjhhubh)}(hIn general, conflicts appear when the context of the patch (i.e., the lines being changed and/or the lines surrounding the changes) doesn't match what's in the tree you are trying to apply the patch *to*.h](hIn general, conflicts appear when the context of the patch (i.e., the lines being changed and/or the lines surrounding the changes) doesn’t match what’s in the tree you are trying to apply the patch }(hjChhhNhNubj)}(h*to*h]hto}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjCubh.}(hjChhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK_hjhhubh)}(hFor backports, what likely happened was that the branch you are backporting from contains patches not in the branch you are backporting to. However, the reverse is also possible. In any case, the result is a conflict that needs to be resolved.h]hFor backports, what likely happened was that the branch you are backporting from contains patches not in the branch you are backporting to. However, the reverse is also possible. In any case, the result is a conflict that needs to be resolved.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKchjhhubh)}(hXBIf your attempted cherry-pick fails with a conflict, git automatically edits the files to include so-called conflict markers showing you where the conflict is and how the two branches have diverged. Resolving the conflict typically means editing the end result in such a way that it takes into account these other commits.h]hXBIf your attempted cherry-pick fails with a conflict, git automatically edits the files to include so-called conflict markers showing you where the conflict is and how the two branches have diverged. Resolving the conflict typically means editing the end result in such a way that it takes into account these other commits.}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjhhubh)}(hyResolving the conflict can be done either by hand in a regular text editor or using a dedicated conflict resolution tool.h]hyResolving the conflict can be done either by hand in a regular text editor or using a dedicated conflict resolution tool.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjhhubh)}(hXMany people prefer to use their regular text editor and edit the conflict directly, as it may be easier to understand what you're doing and to control the final result. There are definitely pros and cons to each method, and sometimes there's value in using both.h]hX Many people prefer to use their regular text editor and edit the conflict directly, as it may be easier to understand what you’re doing and to control the final result. There are definitely pros and cons to each method, and sometimes there’s value in using both.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKqhjhhubh)}(hvWe will not cover using dedicated merge tools here beyond providing some pointers to various tools that you could use:h]hvWe will not cover using dedicated merge tools here beyond providing some pointers to various tools that you could use:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKvhjhhubj;)}(hhh](j@)}(h@`Emacs Ediff mode `__h]h)}(hjh]j)}(hjh]hEmacs Ediff mode}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameEmacs Ediff modej)https://www.emacswiki.org/emacs/EdiffModeuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKyhjubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(h:`vimdiff/gvimdiff `__h]h)}(hjh]j)}(hjh]hvimdiff/gvimdiff}(hjhhhNhNubah}(h]h ]h"]h$]h&]namevimdiff/gvimdiffj#https://linux.die.net/man/1/vimdiffuh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKzhjubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(h+`KDiff3 `__h]h)}(hjh]j)}(hjh]hKDiff3}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameKDiff3jhttp://kdiff3.sourceforge.net/uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhK{hjubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(h>`TortoiseMerge `__h]h)}(hjh]j)}(hjh]h TortoiseMerge}(hjhhhNhNubah}(h]h ]h"]h$]h&]name TortoiseMergej*https://tortoisesvn.net/TortoiseMerge.htmluh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhK|hjubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(h&`Meld `__h]h)}(hj:h]j)}(hj:h]hMeld}(hj?hhhNhNubah}(h]h ]h"]h$]h&]nameMeldjhttps://meldmerge.org/help/uh1jhj<ubah}(h]h ]h"]h$]h&]uh1hhhhK}hj8ubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(hW`P4Merge `__h]h)}(hj]h]j)}(hj]h]hP4Merge}(hjbhhhNhNubah}(h]h ]h"]h$]h&]nameP4MergejIhttps://www.perforce.com/products/helix-core-apps/merge-diff-tool-p4mergeuh1jhj_ubah}(h]h ]h"]h$]h&]uh1hhhhK~hj[ubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(h5`Beyond Compare `__h]h)}(hjh]j)}(hjh]hBeyond Compare}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameBeyond Comparej https://www.scootersoftware.com/uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhj~ubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(hI`IntelliJ `__h]h)}(hjh]j)}(hjh]hIntelliJ}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameIntelliJj:https://www.jetbrains.com/help/idea/resolve-conflicts.htmluh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubj@)}(hF`VSCode `__ h]h)}(hE`VSCode `__h]j)}(hjh]hVSCode}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameVSCodej8https://code.visualstudio.com/docs/editor/versioncontroluh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j?hjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1j:hhhKyhjhhubh)}(hqTo configure git to work with these, see ``git mergetool --help`` or the official `git-mergetool documentation`_.h](h)To configure git to work with these, see }(hjhhhNhNubj')}(h``git mergetool --help``h]hgit mergetool --help}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh or the official }(hjhhhNhNubj)}(h`git-mergetool documentation`_h]hgit-mergetool documentation}(hj hhhNhNubah}(h]h ]h"]h$]h&]namegit-mergetool documentationj&https://git-scm.com/docs/git-mergetooluh1jhjjKubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hG.. _git-mergetool documentation: https://git-scm.com/docs/git-mergetoolh]h}(h]git-mergetool-documentationah ]h"]git-mergetool documentationah$]h&]jj uh1jhKhjhhhhjKubh)}(hhh](h)}(hPrerequisite patchesh]hPrerequisite patches}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj1 hhhhhKubh)}(hXMost conflicts happen because the branch you are backporting to is missing some patches compared to the branch you are backporting *from*. In the more general case (such as merging two independent branches), development could have happened on either branch, or the branches have simply diverged -- perhaps your older branch had some other backports applied to it that themselves needed conflict resolutions, causing a divergence.h](hMost conflicts happen because the branch you are backporting to is missing some patches compared to the branch you are backporting }(hjB hhhNhNubj)}(h*from*h]hfrom}(hjJ hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjB ubhX$. In the more general case (such as merging two independent branches), development could have happened on either branch, or the branches have simply diverged -- perhaps your older branch had some other backports applied to it that themselves needed conflict resolutions, causing a divergence.}(hjB hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj1 hhubh)}(hXIt's important to always identify the commit or commits that caused the conflict, as otherwise you cannot be confident in the correctness of your resolution. As an added bonus, especially if the patch is in an area you're not that familiar with, the changelogs of these commits will often give you the context to understand the code and potential problems or pitfalls with your conflict resolution.h]hXIt’s important to always identify the commit or commits that caused the conflict, as otherwise you cannot be confident in the correctness of your resolution. As an added bonus, especially if the patch is in an area you’re not that familiar with, the changelogs of these commits will often give you the context to understand the code and potential problems or pitfalls with your conflict resolution.}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj1 hhubh)}(hhh](h)}(hgit logh]hgit log}(hjs hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjp hhhhhKubh)}(hXA good first step is to look at ``git log`` for the file that has the conflict -- this is usually sufficient when there aren't a lot of patches to the file, but may get confusing if the file is big and frequently patched. You should run ``git log`` on the range of commits between your currently checked-out branch (``HEAD``) and the parent of the patch you are picking (````), i.e.::h](h A good first step is to look at }(hj hhhNhNubj')}(h ``git log``h]hgit log}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh for the file that has the conflict -- this is usually sufficient when there aren’t a lot of patches to the file, but may get confusing if the file is big and frequently patched. You should run }(hj hhhNhNubj')}(h ``git log``h]hgit log}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubhD on the range of commits between your currently checked-out branch (}(hj hhhNhNubj')}(h``HEAD``h]hHEAD}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh/) and the parent of the patch you are picking (}(hj hhhNhNubj')}(h ````h]h}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh), i.e.:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjp hhubj)}(h!git log HEAD..^ -- h]h!git log HEAD..^ -- }hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjp hhubh)}(hEven better, if you want to restrict this output to a single function (because that's where the conflict appears), you can use the following syntax::h]hEven better, if you want to restrict this output to a single function (because that’s where the conflict appears), you can use the following syntax:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjp hhubj)}(h0git log -L:'\': HEAD..^h]h0git log -L:'\': HEAD..^}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjp hhubhnote)}(hXThe ``\<`` and ``\>`` around the function name ensure that the matches are anchored on a word boundary. This is important, as this part is actually a regex and git only follows the first match, so if you use ``-L:thread_stack:kernel/fork.c`` it may only give you results for the function ``try_release_thread_stack_to_cache`` even though there are many other functions in that file containing the string ``thread_stack`` in their names.h]h)}(hXThe ``\<`` and ``\>`` around the function name ensure that the matches are anchored on a word boundary. This is important, as this part is actually a regex and git only follows the first match, so if you use ``-L:thread_stack:kernel/fork.c`` it may only give you results for the function ``try_release_thread_stack_to_cache`` even though there are many other functions in that file containing the string ``thread_stack`` in their names.h](hThe }(hj hhhNhNubj')}(h``\<``h]h\<}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh and }(hj hhhNhNubj')}(h``\>``h]h\>}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh around the function name ensure that the matches are anchored on a word boundary. This is important, as this part is actually a regex and git only follows the first match, so if you use }(hj hhhNhNubj')}(h!``-L:thread_stack:kernel/fork.c``h]h-L:thread_stack:kernel/fork.c}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh/ it may only give you results for the function }(hj hhhNhNubj')}(h%``try_release_thread_stack_to_cache``h]h!try_release_thread_stack_to_cache}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubhO even though there are many other functions in that file containing the string }(hj hhhNhNubj')}(h``thread_stack``h]h thread_stack}(hjW hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh in their names.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hjp hhhhhNubh)}(hAnother useful option for ``git log`` is ``-G``, which allows you to filter on certain strings appearing in the diffs of the commits you are listing::h](hAnother useful option for }(hju hhhNhNubj')}(h ``git log``h]hgit log}(hj} hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hju ubh is }(hju hhhNhNubj')}(h``-G``h]h-G}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hju ubhf, which allows you to filter on certain strings appearing in the diffs of the commits you are listing:}(hju hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjp hhubj)}(h+git log -G'regex' HEAD..^ -- h]h+git log -G'regex' HEAD..^ -- }hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjp hhubh)}(hXThis can also be a handy way to quickly find when something (e.g. a function call or a variable) was changed, added, or removed. The search string is a regular expression, which means you can potentially search for more specific things like assignments to a specific struct member::h]hXThis can also be a handy way to quickly find when something (e.g. a function call or a variable) was changed, added, or removed. The search string is a regular expression, which means you can potentially search for more specific things like assignments to a specific struct member:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjp hhubj)}(hgit log -G'\->index\>.*='h]hgit log -G'\->index\>.*='}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjp hhubeh}(h]jah ]h"]git logah$]h&]uh1hhj1 hhhhhKubh)}(hhh](h)}(h git blameh]h git blame}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hXAnother way to find prerequisite commits (albeit only the most recent one for a given conflict) is to run ``git blame``. In this case, you need to run it against the parent commit of the patch you are cherry-picking and the file where the conflict appeared, i.e.::h](hjAnother way to find prerequisite commits (albeit only the most recent one for a given conflict) is to run }(hj hhhNhNubj')}(h ``git blame``h]h git blame}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh. In this case, you need to run it against the parent commit of the patch you are cherry-picking and the file where the conflict appeared, i.e.:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj)}(hgit blame ^ -- h]hgit blame ^ -- }hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhj hhubh)}(hThis command also accepts the ``-L`` argument (for restricting the output to a single function), but in this case you specify the filename at the end of the command as usual::h](hThis command also accepts the }(hj hhhNhNubj')}(h``-L``h]h-L}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh argument (for restricting the output to a single function), but in this case you specify the filename at the end of the command as usual:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj)}(h/git blame -L:'\' ^ -- h]h/git blame -L:'\' ^ -- }hj7 sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhj hhubh)}(hNavigate to the place where the conflict occurred. The first column of the blame output is the commit ID of the patch that added a given line of code.h]hNavigate to the place where the conflict occurred. The first column of the blame output is the commit ID of the patch that added a given line of code.}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hXIt might be a good idea to ``git show`` these commits and see if they look like they might be the source of the conflict. Sometimes there will be more than one of these commits, either because multiple commits changed different lines of the same conflict area *or* because multiple subsequent patches changed the same line (or lines) multiple times. In the latter case, you may have to run ``git blame`` again and specify the older version of the file to look at in order to dig further back in the history of the file.h](hIt might be a good idea to }(hjS hhhNhNubj')}(h ``git show``h]hgit show}(hj[ hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjS ubh these commits and see if they look like they might be the source of the conflict. Sometimes there will be more than one of these commits, either because multiple commits changed different lines of the same conflict area }(hjS hhhNhNubj)}(h*or*h]hor}(hjm hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjS ubh~ because multiple subsequent patches changed the same line (or lines) multiple times. In the latter case, you may have to run }(hjS hhhNhNubj')}(h ``git blame``h]h git blame}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjS ubht again and specify the older version of the file to look at in order to dig further back in the history of the file.}(hjS hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]jah ]h"] git blameah$]h&]uh1hhj1 hhhhhKubh)}(hhh](h)}(h#Prerequisite vs. incidental patchesh]h#Prerequisite vs. incidental patches}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hXHaving found the patch that caused the conflict, you need to determine whether it is a prerequisite for the patch you are backporting or whether it is just incidental and can be skipped. An incidental patch would be one that touches the same code as the patch you are backporting, but does not change the semantics of the code in any material way. For example, a whitespace cleanup patch is completely incidental -- likewise, a patch that simply renames a function or a variable would be incidental as well. On the other hand, if the function being changed does not even exist in your current branch then this would not be incidental at all and you need to carefully consider whether the patch adding the function should be cherry-picked first.h]hXHaving found the patch that caused the conflict, you need to determine whether it is a prerequisite for the patch you are backporting or whether it is just incidental and can be skipped. An incidental patch would be one that touches the same code as the patch you are backporting, but does not change the semantics of the code in any material way. For example, a whitespace cleanup patch is completely incidental -- likewise, a patch that simply renames a function or a variable would be incidental as well. On the other hand, if the function being changed does not even exist in your current branch then this would not be incidental at all and you need to carefully consider whether the patch adding the function should be cherry-picked first.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hIf you find that there is a necessary prerequisite patch, then you need to stop and cherry-pick that instead. If you've already resolved some conflicts in a different file and don't want to do it again, you can create a temporary copy of that file.h]hIf you find that there is a necessary prerequisite patch, then you need to stop and cherry-pick that instead. If you’ve already resolved some conflicts in a different file and don’t want to do it again, you can create a temporary copy of that file.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hTo abort the current cherry-pick, go ahead and run ``git cherry-pick --abort``, then restart the cherry-picking process with the commit ID of the prerequisite patch instead.h](h3To abort the current cherry-pick, go ahead and run }(hj hhhNhNubj')}(h``git cherry-pick --abort``h]hgit cherry-pick --abort}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh_, then restart the cherry-picking process with the commit ID of the prerequisite patch instead.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h]jah ]h"]#prerequisite vs. incidental patchesah$]h&]uh1hhj1 hhhhhKubeh}(h]jah ]h"]prerequisite patchesah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hUnderstanding conflict markersh]hUnderstanding conflict markers}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hhh](h)}(hCombined diffsh]hCombined diffs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hLet's say you've decided against picking (or reverting) additional patches and you just want to resolve the conflict. Git will have inserted conflict markers into your file. Out of the box, this will look something like::h]hLet’s say you’ve decided against picking (or reverting) additional patches and you just want to resolve the conflict. Git will have inserted conflict markers into your file. Out of the box, this will look something like:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubj)}(h<<<<<<< HEAD this is what's in your current tree before cherry-picking ======= this is what the patch wants it to be after cherry-picking >>>>>>> ... titleh]h<<<<<<< HEAD this is what's in your current tree before cherry-picking ======= this is what the patch wants it to be after cherry-picking >>>>>>> ... title}hj) sbah}(h]h ]h"]h$]h&]hhuh1jhhhMhj hhubh)}(hThis is what you would see if you opened the file in your editor. However, if you were to run ``git diff`` without any arguments, the output would look something like this::h](h^This is what you would see if you opened the file in your editor. However, if you were to run }(hj7 hhhNhNubj')}(h ``git diff``h]hgit diff}(hj? hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj7 ubhB without any arguments, the output would look something like this:}(hj7 hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h$ git diff [...] ++<<<<<<<< HEAD +this is what's in your current tree before cherry-picking ++======== + this is what the patch wants it to be after cherry-picking ++>>>>>>>> ... titleh]h$ git diff [...] ++<<<<<<<< HEAD +this is what's in your current tree before cherry-picking ++======== + this is what the patch wants it to be after cherry-picking ++>>>>>>>> ... title}hjW sbah}(h]h ]h"]h$]h&]hhuh1jhhhM hj hhubh)}(hXWhen you are resolving a conflict, the behavior of ``git diff`` differs from its normal behavior. Notice the two columns of diff markers instead of the usual one; this is a so-called "`combined diff`_", here showing the 3-way diff (or diff-of-diffs) betweenh](h3When you are resolving a conflict, the behavior of }(hje hhhNhNubj')}(h ``git diff``h]hgit diff}(hjm hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hje ubh{ differs from its normal behavior. Notice the two columns of diff markers instead of the usual one; this is a so-called “}(hje hhhNhNubj)}(h`combined diff`_h]h combined diff}(hj hhhNhNubah}(h]h ]h"]h$]h&]name combined diffj:https://git-scm.com/docs/diff-format#_combined_diff_formatuh1jhje jKubh;”, here showing the 3-way diff (or diff-of-diffs) between}(hje hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubhenumerated_list)}(hhh](j@)}(hQthe current branch (before cherry-picking) and the current working directory, andh]h)}(hQthe current branch (before cherry-picking) and the current working directory, andh]hQthe current branch (before cherry-picking) and the current working directory, and}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j?hj hhhhhNubj@)}(hothe current branch (before cherry-picking) and the file as it looks after the original patch has been applied. h]h)}(hnthe current branch (before cherry-picking) and the file as it looks after the original patch has been applied.h]hnthe current branch (before cherry-picking) and the file as it looks after the original patch has been applied.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j?hj hhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1j hj hhhhhMubj)}(hM.. _combined diff: https://git-scm.com/docs/diff-format#_combined_diff_formath]h}(h] combined-diffah ]h"] combined diffah$]h&]jj uh1jhMhj hhhhjKubeh}(h]jiah ]h"]combined diffsah$]h&]uh1hhj hhhhhKubh)}(hhh](h)}(h Better diffsh]h Better diffs}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM"ubh)}(hX 3-way combined diffs include all the other changes that happened to the file between your current branch and the branch you are cherry-picking from. While this is useful for spotting other changes that you need to take into account, this also makes the output of ``git diff`` somewhat intimidating and difficult to read. You may instead prefer to run ``git diff HEAD`` (or ``git diff --ours``) which shows only the diff between the current branch before cherry-picking and the current working directory. It looks like this::h](hX3-way combined diffs include all the other changes that happened to the file between your current branch and the branch you are cherry-picking from. While this is useful for spotting other changes that you need to take into account, this also makes the output of }(hj hhhNhNubj')}(h ``git diff``h]hgit diff}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubhL somewhat intimidating and difficult to read. You may instead prefer to run }(hj hhhNhNubj')}(h``git diff HEAD``h]h git diff HEAD}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh (or }(hj hhhNhNubj')}(h``git diff --ours``h]hgit diff --ours}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh) which shows only the diff between the current branch before cherry-picking and the current working directory. It looks like this:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM$hj hhubj)}(h$ git diff HEAD [...] +<<<<<<<< HEAD this is what's in your current tree before cherry-picking +======== +this is what the patch wants it to be after cherry-picking +>>>>>>>> ... titleh]h$ git diff HEAD [...] +<<<<<<<< HEAD this is what's in your current tree before cherry-picking +======== +this is what the patch wants it to be after cherry-picking +>>>>>>>> ... title}hjB sbah}(h]h ]h"]h$]h&]hhuh1jhhhM-hj hhubh)}(hAs you can see, this reads just like any other diff and makes it clear which lines are in the current branch and which lines are being added because they are part of the merge conflict or the patch being cherry-picked.h]hAs you can see, this reads just like any other diff and makes it clear which lines are in the current branch and which lines are being added because they are part of the merge conflict or the patch being cherry-picked.}(hjP hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM5hj hhubeh}(h]jah ]h"] better diffsah$]h&]uh1hhj hhhhhM"ubh)}(hhh](h)}(hMerge styles and diff3h]hMerge styles and diff3}(hjh hhhNhNubah}(h]h ]h"]h$]h&]uh1hhje hhhhhM;ubh)}(hThe default conflict marker style shown above is known as the ``merge`` style. There is also another style available, known as the ``diff3`` style, which looks like this::h](h>The default conflict marker style shown above is known as the }(hjv hhhNhNubj')}(h ``merge``h]hmerge}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjv ubh< style. There is also another style available, known as the }(hjv hhhNhNubj')}(h ``diff3``h]hdiff3}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjv ubh style, which looks like this:}(hjv hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM=hje hhubj)}(h<<<<<<< HEAD this is what is in your current tree before cherry-picking ||||||| parent of (title) this is what the patch expected to find there ======= this is what the patch wants it to be after being applied >>>>>>> (title)h]h<<<<<<< HEAD this is what is in your current tree before cherry-picking ||||||| parent of (title) this is what the patch expected to find there ======= this is what the patch wants it to be after being applied >>>>>>> (title)}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMAhje hhubh)}(hXAs you can see, this has 3 parts instead of 2, and includes what git expected to find there but didn't. It is *highly recommended* to use this conflict style as it makes it much clearer what the patch actually changed; i.e., it allows you to compare the before-and-after versions of the file for the commit you are cherry-picking. This allows you to make better decisions about how to resolve the conflict.h](hpAs you can see, this has 3 parts instead of 2, and includes what git expected to find there but didn’t. It is }(hj hhhNhNubj)}(h*highly recommended*h]hhighly recommended}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhX to use this conflict style as it makes it much clearer what the patch actually changed; i.e., it allows you to compare the before-and-after versions of the file for the commit you are cherry-picking. This allows you to make better decisions about how to resolve the conflict.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMIhje hhubh)}(hETo change conflict marker styles, you can use the following command::h]hDTo change conflict marker styles, you can use the following command:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMPhje hhubj)}(h$git config merge.conflictStyle diff3h]h$git config merge.conflictStyle diff3}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhMRhje hhubh)}(hThere is a third option, ``zdiff3``, introduced in `Git 2.35`_, which has the same 3 sections as ``diff3``, but where common lines have been trimmed off, making the conflict area smaller in some cases.h](hThere is a third option, }(hj hhhNhNubj')}(h ``zdiff3``h]hzdiff3}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh, introduced in }(hj hhhNhNubj)}(h `Git 2.35`_h]hGit 2.35}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameGit 2.35j8https://github.blog/2022-01-24-highlights-from-git-2-35/uh1jhj jKubh#, which has the same 3 sections as }(hj hhhNhNubj')}(h ``diff3``h]hdiff3}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh_, but where common lines have been trimmed off, making the conflict area smaller in some cases.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMThje hhubj)}(hF.. _Git 2.35: https://github.blog/2022-01-24-highlights-from-git-2-35/h]h}(h]git-2-35ah ]h"]git 2.35ah$]h&]jjuh1jhMXhje hhhhjKubeh}(h]jah ]h"]merge styles and diff3ah$]h&]uh1hhj hhhhhM;ubeh}(h]jJah ]h"]understanding conflict markersah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h!Iterating on conflict resolutionsh]h!Iterating on conflict resolutions}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjShhhhhM[ubh)}(hXThe first step in any conflict resolution process is to understand the patch you are backporting. For the Linux kernel this is especially important, since an incorrect change can lead to the whole system crashing -- or worse, an undetected security vulnerability.h]hXThe first step in any conflict resolution process is to understand the patch you are backporting. For the Linux kernel this is especially important, since an incorrect change can lead to the whole system crashing -- or worse, an undetected security vulnerability.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM]hjShhubh)}(hXGUnderstanding the patch can be easy or difficult depending on the patch itself, the changelog, and your familiarity with the code being changed. However, a good question for every change (or every hunk of the patch) might be: "Why is this hunk in the patch?" The answers to these questions will inform your conflict resolution.h]hXKUnderstanding the patch can be easy or difficult depending on the patch itself, the changelog, and your familiarity with the code being changed. However, a good question for every change (or every hunk of the patch) might be: “Why is this hunk in the patch?” The answers to these questions will inform your conflict resolution.}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMbhjShhubh)}(hhh](h)}(hResolution processh]hResolution process}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMiubh)}(hXwSometimes the easiest thing to do is to just remove all but the first part of the conflict, leaving the file essentially unchanged, and apply the changes by hand. Perhaps the patch is changing a function call argument from ``0`` to ``1`` while a conflicting change added an entirely new (and insignificant) parameter to the end of the parameter list; in that case, it's easy enough to change the argument from ``0`` to ``1`` by hand and leave the rest of the arguments alone. This technique of manually applying changes is mostly useful if the conflict pulled in a lot of unrelated context that you don't really need to care about.h](hSometimes the easiest thing to do is to just remove all but the first part of the conflict, leaving the file essentially unchanged, and apply the changes by hand. Perhaps the patch is changing a function call argument from }(hjhhhNhNubj')}(h``0``h]h0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh to }(hjhhhNhNubj')}(h``1``h]h1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh while a conflicting change added an entirely new (and insignificant) parameter to the end of the parameter list; in that case, it’s easy enough to change the argument from }(hjhhhNhNubj')}(h``0``h]h0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh to }(hjhhhNhNubj')}(h``1``h]h1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh by hand and leave the rest of the arguments alone. This technique of manually applying changes is mostly useful if the conflict pulled in a lot of unrelated context that you don’t really need to care about.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMkhjhhubh)}(hX>For particularly nasty conflicts with many conflict markers, you can use ``git add`` or ``git add -i`` to selectively stage your resolutions to get them out of the way; this also lets you use ``git diff HEAD`` to always see what remains to be resolved or ``git diff --cached`` to see what your patch looks like so far.h](hIFor particularly nasty conflicts with many conflict markers, you can use }(hjhhhNhNubj')}(h ``git add``h]hgit add}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh or }(hjhhhNhNubj')}(h``git add -i``h]h git add -i}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubhZ to selectively stage your resolutions to get them out of the way; this also lets you use }(hjhhhNhNubj')}(h``git diff HEAD``h]h git diff HEAD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh. to always see what remains to be resolved or }(hjhhhNhNubj')}(h``git diff --cached``h]hgit diff --cached}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh* to see what your patch looks like so far.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMvhjhhubeh}(h]jah ]h"]resolution processah$]h&]uh1hhjShhhhhMiubh)}(hhh](h)}(hDealing with file renamesh]hDealing with file renames}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjDhhhhhM}ubh)}(hX*One of the most annoying things that can happen while backporting a patch is discovering that one of the files being patched has been renamed, as that typically means git won't even put in conflict markers, but will just throw up its hands and say (paraphrased): "Unmerged path! You do the work..."h]hX0One of the most annoying things that can happen while backporting a patch is discovering that one of the files being patched has been renamed, as that typically means git won’t even put in conflict markers, but will just throw up its hands and say (paraphrased): “Unmerged path! You do the work...”}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjDhhubh)}(hX0There are generally a few ways to deal with this. If the patch to the renamed file is small, like a one-line change, the easiest thing is to just go ahead and apply the change by hand and be done with it. On the other hand, if the change is big or complicated, you definitely don't want to do it by hand.h]hX2There are generally a few ways to deal with this. If the patch to the renamed file is small, like a one-line change, the easiest thing is to just go ahead and apply the change by hand and be done with it. On the other hand, if the change is big or complicated, you definitely don’t want to do it by hand.}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjDhhubh)}(hXAs a first pass, you can try something like this, which will lower the rename detection threshold to 30% (by default, git uses 50%, meaning that two files need to have at least 50% in common for it to consider an add-delete pair to be a potential rename)::h]hAs a first pass, you can try something like this, which will lower the rename detection threshold to 30% (by default, git uses 50%, meaning that two files need to have at least 50% in common for it to consider an add-delete pair to be a potential rename):}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjDhhubj)}(h9git cherry-pick -strategy=recursive -Xrename-threshold=30h]h9git cherry-pick -strategy=recursive -Xrename-threshold=30}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjDhhubh)}(hXSometimes the right thing to do will be to also backport the patch that did the rename, but that's definitely not the most common case. Instead, what you can do is to temporarily rename the file in the branch you're backporting to (using ``git mv`` and committing the result), restart the attempt to cherry-pick the patch, rename the file back (``git mv`` and committing again), and finally squash the result using ``git rebase -i`` (see the `rebase tutorial`_) so it appears as a single commit when you are done.h](hSometimes the right thing to do will be to also backport the patch that did the rename, but that’s definitely not the most common case. Instead, what you can do is to temporarily rename the file in the branch you’re backporting to (using }(hjhhhNhNubj')}(h ``git mv``h]hgit mv}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubha and committing the result), restart the attempt to cherry-pick the patch, rename the file back (}(hjhhhNhNubj')}(h ``git mv``h]hgit mv}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh< and committing again), and finally squash the result using }(hjhhhNhNubj')}(h``git rebase -i``h]h git rebase -i}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh (see the }(hjhhhNhNubj)}(h`rebase tutorial`_h]hrebase tutorial}(hjhhhNhNubah}(h]h ]h"]h$]h&]namerebase tutorialjehttps://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ecuh1jhjjKubh5) so it appears as a single commit when you are done.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjDbvhhubj)}(hz.. _rebase tutorial: https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ech]h}(h]rebase-tutorialah ]h"]rebase tutorialah$]h&]jjuh1jhMhjDhhhhjKubeh}(h]jah ]h"]dealing with file renamesah$]h&]uh1hhjShhhhhM}ubeh}(h]jah ]h"]!iterating on conflict resolutionsah$]h&]uh1hhjhhhhhM[ubh)}(hhh](h)}(hGotchash]hGotchas}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hFunction argumentsh]hFunction arguments}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hX/Pay attention to changing function arguments! It's easy to gloss over details and think that two lines are the same but actually they differ in some small detail like which variable was passed as an argument (especially if the two variables are both a single character that look the same, like i and j).h]hX1Pay attention to changing function arguments! It’s easy to gloss over details and think that two lines are the same but actually they differ in some small detail like which variable was passed as an argument (especially if the two variables are both a single character that look the same, like i and j).}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]jiah ]h"]function argumentsah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hError handlingh]hError handling}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj7hhhhhMubh)}(hX"If you cherry-pick a patch that includes a ``goto`` statement (typically for error handling), it is absolutely imperative to double check that the target label is still correct in the branch you are backporting to. The same goes for added ``return``, ``break``, and ``continue`` statements.h](h+If you cherry-pick a patch that includes a }(hjHhhhNhNubj')}(h``goto``h]hgoto}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjHubh statement (typically for error handling), it is absolutely imperative to double check that the target label is still correct in the branch you are backporting to. The same goes for added }(hjHhhhNhNubj')}(h ``return``h]hreturn}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjHubh, }(hjHhhhNhNubj')}(h ``break``h]hbreak}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjHubh, and }(hjHhhhNhNubj')}(h ``continue``h]hcontinue}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjHubh statements.}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj7hhubh)}(hError handling is typically located at the bottom of the function, so it may not be part of the conflict even though it could have been changed by other patches.h]hError handling is typically located at the bottom of the function, so it may not be part of the conflict even though it could have been changed by other patches.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj7hhubh)}(hX"A good way to ensure that you review the error paths is to always use ``git diff -W`` and ``git show -W`` (AKA ``--function-context``) when inspecting your changes. For C code, this will show you the whole function that's being changed in a patch. One of the things that often go wrong during backports is that something else in the function changed on either of the branches that you're backporting from or to. By including the whole function in the diff you get more context and can more easily spot problems that might otherwise go unnoticed.h](hFA good way to ensure that you review the error paths is to always use }(hjhhhNhNubj')}(h``git diff -W``h]h git diff -W}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh and }(hjhhhNhNubj')}(h``git show -W``h]h git show -W}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh (AKA }(hjhhhNhNubj')}(h``--function-context``h]h--function-context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubhX) when inspecting your changes. For C code, this will show you the whole function that’s being changed in a patch. One of the things that often go wrong during backports is that something else in the function changed on either of the branches that you’re backporting from or to. By including the whole function in the diff you get more context and can more easily spot problems that might otherwise go unnoticed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj7hhubeh}(h]jah ]h"]error handlingah$]h&]uh1hhjhhhhhMubh)}(hhh](h)}(hRefactored codeh]hRefactored code}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hXSomething that happens quite often is that code gets refactored by "factoring out" a common code sequence or pattern into a helper function. When backporting patches to an area where such a refactoring has taken place, you effectively need to do the reverse when backporting: a patch to a single location may need to be applied to multiple locations in the backported version. (One giveaway for this scenario is that a function was renamed -- but that's not always the case.)h]hXSomething that happens quite often is that code gets refactored by “factoring out” a common code sequence or pattern into a helper function. When backporting patches to an area where such a refactoring has taken place, you effectively need to do the reverse when backporting: a patch to a single location may need to be applied to multiple locations in the backported version. (One giveaway for this scenario is that a function was renamed -- but that’s not always the case.)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hX5To avoid incomplete backports, it's worth trying to figure out if the patch fixes a bug that appears in more than one place. One way to do this would be to use ``git grep``. (This is actually a good idea to do in general, not just for backports.) If you do find that the same kind of fix would apply to other places, it's also worth seeing if those places exist upstream -- if they don't, it's likely the patch may need to be adjusted. ``git log`` is your friend to figure out what happened to these areas as ``git blame`` won't show you code that has been removed.h](hTo avoid incomplete backports, it’s worth trying to figure out if the patch fixes a bug that appears in more than one place. One way to do this would be to use }(hjhhhNhNubj')}(h ``git grep``h]hgit grep}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubhX. (This is actually a good idea to do in general, not just for backports.) If you do find that the same kind of fix would apply to other places, it’s also worth seeing if those places exist upstream -- if they don’t, it’s likely the patch may need to be adjusted. }(hjhhhNhNubj')}(h ``git log``h]hgit log}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh> is your friend to figure out what happened to these areas as }(hjhhhNhNubj')}(h ``git blame``h]h git blame}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh- won’t show you code that has been removed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hIf you do find other instances of the same pattern in the upstream tree and you're not sure whether it's also a bug, it may be worth asking the patch author. It's not uncommon to find new bugs during backporting!h]hIf you do find other instances of the same pattern in the upstream tree and you’re not sure whether it’s also a bug, it may be worth asking the patch author. It’s not uncommon to find new bugs during backporting!}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]jah ]h"]refactored codeah$]h&]uh1hhjhhhhhMubeh}(h]jJah ]h"]gotchasah$]h&]uh1hhjhhhhhMubeh}(h]jah ]h"]resolving conflictsah$]h&]uh1hhhhhhhhKWubh)}(hhh](h)}(hVerifying the resulth]hVerifying the result}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj}hhhhhMubh)}(hhh](h)}(h colordiffh]h colordiff}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hHaving committed a conflict-free new patch, you can now compare your patch to the original patch. It is highly recommended that you use a tool such as `colordiff`_ that can show two files side by side and color them according to the changes between them::h](hHaving committed a conflict-free new patch, you can now compare your patch to the original patch. It is highly recommended that you use a tool such as }(hjhhhNhNubj)}(h `colordiff`_h]h colordiff}(hjhhhNhNubah}(h]h ]h"]h$]h&]name colordiffjhttps://www.colordiff.org/uh1jhjjKubh[ that can show two files side by side and color them according to the changes between them:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hXcolordiff -yw -W 200 <(git diff -W ^-) <(git diff -W HEAD^-) | less -SRh]hXcolordiff -yw -W 200 <(git diff -W ^-) <(git diff -W HEAD^-) | less -SR}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhMhjhhubj)}(h).. _colordiff: https://www.colordiff.org/h]h}(h]id1ah ]h"] colordiffah$]h&]jjuh1jhMhjhhhhjKubh)}(hHere, ``-y`` means to do a side-by-side comparison; ``-w`` ignores whitespace, and ``-W 200`` sets the width of the output (as otherwise it will use 130 by default, which is often a bit too little).h](hHere, }(hjhhhNhNubj')}(h``-y``h]h-y}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh( means to do a side-by-side comparison; }(hjhhhNhNubj')}(h``-w``h]h-w}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh ignores whitespace, and }(hjhhhNhNubj')}(h ``-W 200``h]h-W 200}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubhi sets the width of the output (as otherwise it will use 130 by default, which is often a bit too little).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hThe ``rev^-`` syntax is a handy shorthand for ``rev^..rev``, essentially giving you just the diff for that single commit; also see the official `git rev-parse documentation`_.h](hThe }(hj hhhNhNubj')}(h ``rev^-``h]hrev^-}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubh! syntax is a handy shorthand for }(hj hhhNhNubj')}(h ``rev^..rev``h]h rev^..rev}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hj ubhU, essentially giving you just the diff for that single commit; also see the official }(hj hhhNhNubj)}(h`git rev-parse documentation`_h]hgit rev-parse documentation}(hjLhhhNhNubah}(h]h ]h"]h$]h&]namegit rev-parse documentationjLhttps://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand_notationsuh1jhj jKubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hm.. _git rev-parse documentation: https://git-scm.com/docs/git-rev-parse#_other_rev_parent_shorthand_notationsh]h}(h]git-rev-parse-documentationah ]h"]git rev-parse documentationah$]h&]jj\uh1jhMhjhhhhjKubh)}(hAgain, note the inclusion of ``-W`` for ``git diff``; this ensures that you will see the full function for any function that has changed.h](hAgain, note the inclusion of }(hjshhhNhNubj')}(h``-W``h]h-W}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjsubh for }(hjshhhNhNubj')}(h ``git diff``h]hgit diff}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjsubhU; this ensures that you will see the full function for any function that has changed.}(hjshhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXOne incredibly important thing that colordiff does is to highlight lines that are different. For example, if an error-handling ``goto`` has changed labels between the original and backported patch, colordiff will show these side-by-side but highlighted in a different color. Thus, it is easy to see that the two ``goto`` statements are jumping to different labels. Likewise, lines that were not modified by either patch but differ in the context will also be highlighted and thus stand out during a manual inspection.h](hOne incredibly important thing that colordiff does is to highlight lines that are different. For example, if an error-handling }(hjhhhNhNubj')}(h``goto``h]hgoto}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh has changed labels between the original and backported patch, colordiff will show these side-by-side but highlighted in a different color. Thus, it is easy to see that the two }(hjhhhNhNubj')}(h``goto``h]hgoto}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh statements are jumping to different labels. Likewise, lines that were not modified by either patch but differ in the context will also be highlighted and thus stand out during a manual inspection.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hsOf course, this is just a visual inspection; the real test is building and running the patched kernel (or program).h]hsOf course, this is just a visual inspection; the real test is building and running the patched kernel (or program).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]jah ]h"]h$]jah&]uh1hhj}hhhhhMjKubh)}(hhh](h)}(h Build testingh]h Build testing}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hX We won't cover runtime testing here, but it can be a good idea to build just the files touched by the patch as a quick sanity check. For the Linux kernel you can build single files like this, assuming you have the ``.config`` and build environment set up correctly::h](hWe won’t cover runtime testing here, but it can be a good idea to build just the files touched by the patch as a quick sanity check. For the Linux kernel you can build single files like this, assuming you have the }(hjhhhNhNubj')}(h ``.config``h]h.config}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh( and build environment set up correctly:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hmake path/to/file.oh]hmake path/to/file.o}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhM hjhhubh)}(hXNote that this won't discover linker errors, so you should still do a full build after verifying that the single file compiles. By compiling the single file first you can avoid having to wait for a full build *in case* there are compiler errors in any of the files you've changed.h](hNote that this won’t discover linker errors, so you should still do a full build after verifying that the single file compiles. By compiling the single file first you can avoid having to wait for a full build }(hj*hhhNhNubj)}(h *in case*h]hin case}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj*ubh@ there are compiler errors in any of the files you’ve changed.}(hj*hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjhhubeh}(h]j(ah ]h"] build testingah$]h&]uh1hhj}hhhhhMubh)}(hhh](h)}(hRuntime testingh]hRuntime testing}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQhhhhhMubh)}(hX6Even a successful build or boot test is not necessarily enough to rule out a missing dependency somewhere. Even though the chances are small, there could be code changes where two independent changes to the same file result in no conflicts, no compile-time errors, and runtime errors only in exceptional cases.h]hX6Even a successful build or boot test is not necessarily enough to rule out a missing dependency somewhere. Even though the chances are small, there could be code changes where two independent changes to the same file result in no conflicts, no compile-time errors, and runtime errors only in exceptional cases.}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjQhhubh)}(hXOne concrete example of this was a pair of patches to the system call entry code where the first patch saved/restored a register and a later patch made use of the same register somewhere in the middle of this sequence. Since there was no overlap between the changes, one could cherry-pick the second patch, have no conflicts, and believe that everything was fine, when in fact the code was now scribbling over an unsaved register.h]hXOne concrete example of this was a pair of patches to the system call entry code where the first patch saved/restored a register and a later patch made use of the same register somewhere in the middle of this sequence. Since there was no overlap between the changes, one could cherry-pick the second patch, have no conflicts, and believe that everything was fine, when in fact the code was now scribbling over an unsaved register.}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjQhhubh)}(hXAlthough the vast majority of errors will be caught during compilation or by superficially exercising the code, the only way to *really* verify a backport is to review the final patch with the same level of scrutiny as you would (or should) give to any other patch. Having unit tests and regression tests or other types of automatic testing can help increase the confidence in the correctness of a backport.h](hAlthough the vast majority of errors will be caught during compilation or by superficially exercising the code, the only way to }(hj~hhhNhNubj)}(h*really*h]hreally}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj~ubhX verify a backport is to review the final patch with the same level of scrutiny as you would (or should) give to any other patch. Having unit tests and regression tests or other types of automatic testing can help increase the confidence in the correctness of a backport.}(hj~hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM!hjQhhubeh}(h]jJah ]h"]runtime testingah$]h&]uh1hhj}hhhhhMubeh}(h]jah ]h"]verifying the resultah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hSubmitting backports to stableh]hSubmitting backports to stable}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM)ubh)}(hXnAs the stable maintainers try to cherry-pick mainline fixes onto their stable kernels, they may send out emails asking for backports when encountering conflicts, see e.g. . These emails typically include the exact steps you need to cherry-pick the patch to the correct tree and submit the patch.h](hAs the stable maintainers try to cherry-pick mainline fixes onto their stable kernels, they may send out emails asking for backports when encountering conflicts, see e.g. <}(hjhhhNhNubj)}(hEhttps://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/h]hEhttps://lore.kernel.org/stable/2023101528-jawed-shelving-071a@gregkh/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubh}>. These emails typically include the exact steps you need to cherry-pick the patch to the correct tree and submit the patch.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM+hjhhubh)}(hOOne thing to make sure is that your changelog conforms to the expected format::h]hNOne thing to make sure is that your changelog conforms to the expected format:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hjhhubj)}(h [ Upstream commit ] [ ] Signed-off-by: h]h [ Upstream commit ] [ ] Signed-off-by: }hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhM5hjhhubh)}(h|The "Upstream commit" line is sometimes slightly different depending on the stable version. Older version used this format::h]hThe “Upstream commit” line is sometimes slightly different depending on the stable version. Older version used this format:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM=hjhhubj)}(hcommit upstream.h]hcommit upstream.}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhM@hjhhubh)}(hIt is most common to indicate the kernel version the patch applies to in the email subject line (using e.g. ``git send-email --subject-prefix='PATCH 6.1.y'``), but you can also put it in the Signed-off-by:-area or below the ``---`` line.h](hlIt is most common to indicate the kernel version the patch applies to in the email subject line (using e.g. }(hjhhhNhNubj')}(h1``git send-email --subject-prefix='PATCH 6.1.y'``h]h-git send-email --subject-prefix='PATCH 6.1.y'}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubhC), but you can also put it in the Signed-off-by:-area or below the }(hjhhhNhNubj')}(h``---``h]h---}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1j&hjubh line.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMBhjhhubh)}(hThe stable maintainers expect separate submissions for each active stable version, and each submission should also be tested separately.h]hThe stable maintainers expect separate submissions for each active stable version, and each submission should also be tested separately.}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMGhjhhubeh}(h]jxah ]h"]submitting backports to stableah$]h&]uh1hhhhhhhhM)ubh)}(hhh](h)}(hA few final words of adviceh]hA few final words of advice}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj]hhhhhMKubj )}(hhh](j@)}(h/Approach the backporting process with humility.h]h)}(hjsh]h/Approach the backporting process with humility.}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMMhjqubah}(h]h ]h"]h$]h&]uh1j?hjnhhhhhNubj@)}(h]Understand the patch you are backporting; this means reading both the changelog and the code.h]h)}(h]Understand the patch you are backporting; this means reading both the changelog and the code.h]h]Understand the patch you are backporting; this means reading both the changelog and the code.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhjubah}(h]h ]h"]h$]h&]uh1j?hjnhhhhhNubj@)}(hHBe honest about your confidence in the result when submitting the patch.h]h)}(hHBe honest about your confidence in the result when submitting the patch.h]hHBe honest about your confidence in the result when submitting the patch.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMPhjubah}(h]h ]h"]h$]h&]uh1j?hjnhhhhhNubj@)}(h,Ask relevant maintainers for explicit acks. h]h)}(h+Ask relevant maintainers for explicit acks.h]h+Ask relevant maintainers for explicit acks.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjubah}(h]h ]h"]h$]h&]uh1j?hjnhhhhhNubeh}(h]h ]h"]h$]h&]j j j hj )uh1j hj]hhhhhMMubeh}(h]jah ]h"]a few final words of adviceah$]h&]uh1hhhhhhhhMKubh)}(hhh](h)}(hExamplesh]hExamples}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMUubh)}(hThe above shows roughly the idealized process of backporting a patch. For a more concrete example, see this video tutorial where two patches are backported from mainline to stable: `Backporting Linux Kernel Patches`_.h](hThe above shows roughly the idealized process of backporting a patch. For a more concrete example, see this video tutorial where two patches are backported from mainline to stable: }(hjhhhNhNubj)}(h#`Backporting Linux Kernel Patches`_h]h Backporting Linux Kernel Patches}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Backporting Linux Kernel Patchesjhttps://youtu.be/sBR7R1V2FeAuh1jhjjKubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMWhjhhubj)}(hB.. _Backporting Linux Kernel Patches: https://youtu.be/sBR7R1V2FeAh]h}(h] backporting-linux-kernel-patchesah ]h"] backporting linux kernel patchesah$]h&]jjuh1jhM\hjhhhhjKubeh}(h]jah ]h"]examplesah$]h&]uh1hhhhhhhhMUubeh}(h]#backporting-and-conflict-resolutionah ]h"]#backporting and conflict resolutionah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjPerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}(b4]jab4 presentation]j_agit-mergetool documentation]j a combined diff]j agit 2.35]j arebase tutorial]ja colordiff]jagit rev-parse documentation]jLa backporting linux kernel patches]jaurefids}nameids}(j*j'jjj jVjjxjjjjjzjj. j+ j jj jj jj jjPjJj jij j jb jjIjjBj?jjjAjjjjjjsjJj4jijjjljjj colordiffjjpjmjNj(jjJjZjxjjj"jjju nametypes}(j*jj jjjjzj. j j j j jPj j jb jIjBjjAjjjsj4jjljjjpjNjjZjj"juh}(j'hjj7jVjjxj jjjjjjj+ j% jj1 jjp jj jj jJj jij j j jj jje j?j9jjSjjjjDjjjJjjijjj7jjjj}jjjjjmjgj(jjJjQjxjjj]jjjjjPjGjrjijjjjjjjjjj jDj;jcjZjj|jjjjjjjj jDj;jcjZjj|jjjjjjj"jjDj;jrjijjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j^KsRparse_messages]hsystem_message)}(hhh]h)}(h,Duplicate implicit target name: "colordiff".h]h0Duplicate implicit target name: “colordiff”.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jalevelKtypeINFOlineMsourcehuh1jhjhhhhhMubatransform_messages] transformerN include_log] decorationNhhub.