git log¶

A good first step is to look atgitlog for the file that has theconflict -- this is usually sufficient when there aren’t a lot ofpatches to the file, but may get confusing if the file is big andfrequently patched. You should rungitlog on the range of commitsbetween your currently checked-out branch (HEAD) and the parent ofthe patch you are picking (<commit>), i.e.:

git log HEAD..<commit>^ -- <path>

Even better, if you want to restrict this output to a single function(because that’s where the conflict appears), you can use the followingsyntax:

git log -L:'\<function\>':<path> HEAD..<commit>^

Another useful option forgitlog is-G, which allows you tofilter on certain strings appearing in the diffs of the commits you arelisting:

git log -G'regex' HEAD..<commit>^ -- <path>

This can also be a handy way to quickly find when something (e.g. afunction call or a variable) was changed, added, or removed. The searchstring is a regular expression, which means you can potentially searchfor more specific things like assignments to a specificstructmember:

git log -G'\->index\>.*='

git blame¶

Another way to find prerequisite commits (albeit only the most recentone for a given conflict) is to rungitblame. In this case, youneed to run it against the parent commit of the patch you arecherry-picking and the file where the conflict appeared, i.e.:

git blame <commit>^ -- <path>

This command also accepts the-L argument (for restricting theoutput to a single function), but in this case you specify the filenameat the end of the command as usual:

git blame -L:'\<function\>' <commit>^ -- <path>

Navigate to the place where the conflict occurred. The first column ofthe blame output is the commit ID of the patch that added a given lineof code.

It might be a good idea togitshow these commits and see if theylook like they might be the source of the conflict. Sometimes there willbe more than one of these commits, either because multiple commitschanged different lines of the same conflict areaor because multiplesubsequent patches changed the same line (or lines) multiple times. Inthe latter case, you may have to rungitblame again and specify theolder version of the file to look at in order to dig further back inthe history of the file.

Prerequisite vs. incidental patches¶

Having found the patch that caused the conflict, you need to determinewhether it is a prerequisite for the patch you are backporting orwhether it is just incidental and can be skipped. An incidental patchwould be one that touches the same code as the patch you arebackporting, but does not change the semantics of the code in anymaterial way. For example, a whitespace cleanup patch is completelyincidental -- likewise, a patch that simply renames a function or avariable would be incidental as well. On the other hand, if the functionbeing changed does not even exist in your current branch then this wouldnot be incidental at all and you need to carefully consider whether thepatch adding the function should be cherry-picked first.

If you find that there is a necessary prerequisite patch, then you needto stop and cherry-pick that instead. If you’ve already resolved someconflicts in a different file and don’t want to do it again, you cancreate a temporary copy of that file.

To abort the current cherry-pick, go ahead and rungitcherry-pick--abort, then restart the cherry-picking processwith the commit ID of the prerequisite patch instead.

Combined diffs¶

Let’s say you’ve decided against picking (or reverting) additionalpatches and you just want to resolve the conflict. Git will haveinserted conflict markers into your file. Out of the box, this will looksomething like:

<<<<<<< HEADthis is what's in your current tree before cherry-picking=======this is what the patch wants it to be after cherry-picking>>>>>>> <commit>... title

This is what you would see if you opened the file in your editor.However, if you were to rungitdiff without any arguments, theoutput would look something like this:

$ 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++>>>>>>>> <commit>... title

When you are resolving a conflict, the behavior ofgitdiff differsfrom its normal behavior. Notice the two columns of diff markersinstead of the usual one; this is a so-called “combined diff”, hereshowing the 3-way diff (or diff-of-diffs) between

1. the current branch (before cherry-picking) and the current workingdirectory, and

2. the current branch (before cherry-picking) and the file as it looksafter the original patch has been applied.

Better diffs¶

3-way combined diffs include all the other changes that happened to thefile between your current branch and the branch you are cherry-pickingfrom. While this is useful for spotting other changes that you need totake into account, this also makes the output ofgitdiff somewhatintimidating and difficult to read. You may instead prefer to rungitdiffHEAD (orgitdiff--ours) which shows only the diffbetween the current branch before cherry-picking and the current workingdirectory. It looks like this:

$ 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+>>>>>>>> <commit>... title

As you can see, this reads just like any other diff and makes it clearwhich lines are in the current branch and which lines are being addedbecause they are part of the merge conflict or the patch beingcherry-picked.

Merge styles and diff3¶

The default conflict marker style shown above is known as themergestyle. There is also another style available, known as thediff3style, which looks like this:

<<<<<<< HEADthis is what is in your current tree before cherry-picking||||||| parent of <commit> (title)this is what the patch expected to find there=======this is what the patch wants it to be after being applied>>>>>>> <commit> (title)

As you can see, this has 3 parts instead of 2, and includes what gitexpected to find there but didn’t. It ishighly recommended to usethis conflict style as it makes it much clearer what the patch actuallychanged; i.e., it allows you to compare the before-and-after versionsof the file for the commit you are cherry-picking. This allows you tomake better decisions about how to resolve the conflict.

To change conflict marker styles, you can use the following command:

git config merge.conflictStyle diff3

There is a third option,zdiff3, introduced inGit 2.35,which has the same 3 sections asdiff3, but where common lines havebeen trimmed off, making the conflict area smaller in some cases.

Resolution process¶

Sometimes the easiest thing to do is to just remove all but the firstpart of the conflict, leaving the file essentially unchanged, and applythe changes by hand. Perhaps the patch is changing a function callargument from0 to1 while a conflicting change added anentirely new (and insignificant) parameter to the end of the parameterlist; in that case, it’s easy enough to change the argument from0to1 by hand and leave the rest of the arguments alone. Thistechnique of manually applying changes is mostly useful if the conflictpulled in a lot of unrelated context that you don’t really need to careabout.

For particularly nasty conflicts with many conflict markers, you can usegitadd orgitadd-i to selectively stage your resolutions toget them out of the way; this also lets you usegitdiffHEAD toalways see what remains to be resolved orgitdiff--cached to seewhat your patch looks like so far.

Dealing with file renames¶

One of the most annoying things that can happen while backporting apatch is discovering that one of the files being patched has beenrenamed, 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...”

There are generally a few ways to deal with this. If the patch to therenamed file is small, like a one-line change, the easiest thing is tojust go ahead and apply the change by hand and be done with it. On theother hand, if the change is big or complicated, you definitely don’twant to do it by hand.

As a first pass, you can try something like this, which will lower therename detection threshold to 30% (by default, git uses 50%, meaningthat two files need to have at least 50% in common for it to consideran add-delete pair to be a potential rename):

git cherry-pick -strategy=recursive -Xrename-threshold=30

Sometimes the right thing to do will be to also backport the patch thatdid 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’rebackporting to (usinggitmv and committing the result), restart theattempt to cherry-pick the patch, rename the file back (gitmv andcommitting again), and finally squash the result usinggitrebase-i(see therebase tutorial) so it appears as a single commit when youare done.

Function arguments¶

Pay attention to changing function arguments! It’s easy to gloss overdetails and think that two lines are the same but actually they differin some small detail like which variable was passed as an argument(especially if the two variables are both a single character that lookthe same, like i and j).

Error handling¶

If you cherry-pick a patch that includes agoto statement (typicallyfor error handling), it is absolutely imperative to double check thatthe target label is still correct in the branch you are backporting to.The same goes for addedreturn,break, andcontinuestatements.

Error handling is typically located at the bottom of the function, so itmay not be part of the conflict even though could have been changed byother patches.

A good way to ensure that you review the error paths is to always usegitdiff-W andgitshow-W (AKA--function-context) wheninspecting your changes. For C code, this will show you the wholefunction that’s being changed in a patch. One of the things that oftengo wrong during backports is that something else in the function changedon either of the branches that you’re backporting from or to. Byincluding the whole function in the diff you get more context and canmore easily spot problems that might otherwise go unnoticed.

Refactored code¶

Something that happens quite often is that code gets refactored by“factoring out” a common code sequence or pattern into a helperfunction. When backporting patches to an area where such a refactoringhas taken place, you effectively need to do the reverse whenbackporting: a patch to a single location may need to be applied tomultiple locations in the backported version. (One giveaway for thisscenario is that a function was renamed -- but that’s not always thecase.)

To avoid incomplete backports, it’s worth trying to figure out if thepatch fixes a bug that appears in more than one place. One way to dothis would be to usegitgrep. (This is actually a good idea to doin general, not just for backports.) If you do find that the same kindof fix would apply to other places, it’s also worth seeing if thoseplaces exist upstream -- if they don’t, it’s likely the patch may needto be adjusted.gitlog is your friend to figure out what happenedto these areas asgitblame won’t show you code that has beenremoved.

If you do find other instances of the same pattern in the upstream treeand you’re not sure whether it’s also a bug, it may be worth asking thepatch author. It’s not uncommon to find new bugs during backporting!