There is nothing built in to Git that will do this automatically, and using the things that are built in to Git, there is no merge strategy (as in running git -merge -s <stretegy>
) that will treat merge drivers (as in merge=<driver>
in .gitattributes
the way you want either.
The above is the bad news; the rest is merely explanation of how we get to this bad news. What it means, in terms of what you're doing, is that you cannot get Git to do the merges the way you want. You can merge by hand, perhaps using git merge --no-commit <arguments>
, in which case you may want to use -X no-renames
as well. Or, you may want to adopt a totally different approach, that does not attempt to use git merge
at all.
What you need to know before even thinking about the problem
There are two basic and fundamental issue we must address first. You describe files existing in branches, but in Git, files aren't actually in branches at all. Files are stored in commits, as a snapshot of a tree. This sounds nitpicky because it is nitpicky, but it's also critical to understanding what Git, which is also nitpicky, sees when you run git merge
.
Two commits and a merge base
When you run git merge
, git starts with three sets of files in three specific commits. I like to refer to these three commits as L for Left-side or Local or --ours
, R for Right-side or Remote or --theirs
, and B for the merge base. In general, there must be exactly one merge base commit. To find the merge base's hash ID, you can run git merge-base --all L R
. (If this prints more than one hash ID, things get a little complicated.)
The merge base of two branch tips is, roughly speaking, the first commit at which the branch histories rejoin (the one closest to both branch tips). The first time you ever merge two branches that have diverged, this merge base is the commit that they had in common before they diverged:
o--o--L <-- ourbranch (HEAD)
/
...--o--B
\
o--o--R <-- theirbranch
Once you've done at least one successful merge, however, the merge base is now an immediate ancestor of the previous merge of the two branch tips:
...--o--*--o--L <-- ourbranch (HEAD)
/
...---B--o--o--R <-- theirbranch
The commit marked *
is from the previous merge, and the new merge base B
is its second parent.
The choice of merge base affects every following step, so it's quite crucial. Git makes this choice on its own, with no input from you: it's based strictly on the history Git sees by looking at the commits in the repository (note that the commits are the history).
Rename detection
At this point, for the standard built in recursive or resolve strategy (-s recursive
is the default), the changes Git will look for amount to running:
git diff --find-renames $B $L > /tmp/ourchanges
git diff --find-renames $B $R > /tmp/theirchanges
The --find-renames
part is how Git decides to match up files by name, which in your case is quite critical because of this whole idea that there are going to be different file-sets in L and R.
Renames and other high level changes
Since there's only one merge base commit B, the fact that the set-of-file-names in L and R differ mean that Git will find some set of:
- renames from B to one or both branch tips;
- creations of new files from B to one or both branch tips; and/or
- deletions of existing files from B to one or both branch tips.
These operations—the creating, deleting, and renaming of files—are what I call "high level" changes. It's only after Git has matched up all of these high level operations, and resolved them or declared them to be in conflict, that Git will go on to look for lower level conflicts.
The precise set of creates, deletes, and/or renames that Git will find depends on several things. In particular the --find-renames
code starts by assuming that a file named path/to/file.ext
is the same file in both B and whichever branch tip or tips have that same path. So if any given path exists in all three commits, this file is not renamed in either branch.
If the name exists in B but not in L, it may have been renamed in the left side changes, i.e., --ours
. If the name exists in B but not in R, it may have been renamed in the right side changes. To decide if that B file that seems to have gone missing in either or both of L or R was renamed, Git looks at all the files in the tip commit it's examining right now (L or R). Which of these files have not yet been paired up with a file in B? Each of those is a candidate for rename detection. Git calculates a "similarity index" between the file in B that has gone missing, and each of the target candidate files. If the similarity index is 50% or better, Git declares that the file is renamed (choosing the "best index" if there are multiple matches).
You can set this rename threshold to something other than 50% with -X find-renames=<number>
, or disable rename detection entirely with -X no-renames
. If your Git is fairly old you have a different spelling for this -X
extended-argument, -X rename-threshold
, but it still exists.
Once Git has finished making its list of renames—i.e., finished pairing B files with L or R files—any remaining files that are in B and not the other commit were, in Git's eyes, deleted; and any remaining files in the other commit that are not in B were, in Git's eyes, created.
Now that Git has this complete list of pairings of files in B-vs-L and in B-vs-R, leaving it with lists of high level "creates", "deletes", and "renames", now Git goes on to attempt the merge.
Thinking about the problem
Now that we have the proper terminology and know what Git thinks it's doing, we can look at the merge process. Merge first has to apply all the "high level" changes it has discovered that involve creating, deleting, and/or renaming some files; then it has to apply all the "low level" changes that actually touch lines within files.
Either kind of change can produce a merge conflict—but, importantly, a merge driver is only invoked to deal with a low level conflict. The presence, and some of the detailed workings of, the index come into play here. Remember that the index holds the next commit Git will make. Normally, it has one entry for each file, but during merging, it has three "higher stage" entries for each file: stage 1 for the merge base version, stage 2 for the left/local/--ours
version, and stage 3 for the right/remote/--theirs
version. For high level conflicts, several of these stage slots may be left empty.
High level conflicts
Git first needs to resolve any high level operations. Suppose, for instance, file wasbase
in B became newname
in L, but is still named wasbase
in R. The resolution of this particular clash is easy: keep the rename, by keeping the name newname
in the merge result. Git will soon take any changes we made:
git diff $B:wasbase $L:newname > changes-we-made
git diff $B:wasbase $R:wasbase > changes-they-made
and combine those changes—but for the moment, Git says, in effect: Renamed in our branch but not in their branch, so take the one name-change from our branch.
The same goes for a file that is renamed from B to R, but not from B to L: Git takes the rename, renaming wasbase
to newname
from R even though the result will be committed in our branch rather than theirs. Again, Git says: Renamed in just one branch, so take the one name-change from their branch.
For a file that is renamed in both branches, Git declares a merge conflict: Renamed in both branches, I'm not sure which new name to use. It will still go on to merge the file's changes from both branches as usual, it just doesn't know which new name to keep. (It defaults to using our name and makes you decide whether that is correct.)
If a file is deleted in one branch but not the other, that "deletion" counts as a change to every line of the file. If there are no changes in the other branch, Git believes the correct resolution is to delete the file. Otherwise, Git keeps the (modified) file but declares a conflict. Note that rename vs delete is a conflict as well: the rename counts as a change, for this particular purpose.
If a file is created in one branch but not the other, that "creation" does not conflict: Git keeps the new file. Since there are no changes in whichever branch didn't create the file, there is no low level conflict here either. If it's created in both branches, Git declares an add/add conflict.
Note that if you disable rename detection, you will never get a rename/anything conflict, which will reduce the problem set to add/add and/or modify/delete conflicts. With or without rename detection, you will almost certainly have to manually "undo" some deletes in your particular scenario. Git will see these as unconflicted deletes, where some file existed in B but is deliberately not in the tip of one of your two branches, even though it should remain in the other.
Index manipulation, and handling low level conflicts
All of these changes are recorded by writing files into the index with the appropriate stages and names. The index now has:
- a stage 1 entry for any B file, under its B name;
- a stage 2 entry for any L file, under its L name; and
- a stage 3 entry for any R file, under its R name.
(The index needs, but does not have, some sort of linkage information in case these names differ. The merge strategy knows the linkage, but it's not available to the merge drivers, and as soon as the merge strategy exits due to any conflicts, some information may be irretrievably lost, depending on the exact set of conflicts.)
Git actually stores files by blob hash ID. These three index entries therefore are <file-mode, file-name, hash-ID> triples. Git now does a very fast pass to resolve all the easy cases:
If all three entries have the same hash, the file is unchanged. Toss the high level entries and write a single stage-zero entry with the appropriate new name.
If the file exists only in stage 1 and not in 2 or 3, the file was deleted in both branches. Delete it from stage 1 as well, and it's now completely deleted and merged.
Similarly, if the file exists in stage 1 and has the same hash in 2 or 3 but is gone from the other, it was deleted in one branch but not modified in the other. Delete it from both remaining stages, and it's now completely deleted and merged.
If the file exists only in stage 2 or only in stage 3, the file was created in just one branch. Promote the single entry to stage 0 and the file is now created and merged.
If the file exists in both 2 and 3 but not 1, the file was created in both branches (high level add/add conflict). Leave it this way. (One could argue that this is easily resolved and Git should just collapse this to a single stage-0 entry. I tested it once, though, and if I recall correctly, the conflict happens even if the two hashes match. See also the 3-way merge description in the git read-tree
documentation.)
Otherwise, the file exists in all three commits, and may need a low level merge. This is the only case that invokes a merge driver.
Let's make this a table so that we can see that we have covered all cases:
stage 1 stage 2 stage 3
===============================================================
------- ------- ------- file doesn't exist (can't happen)
------- ------- hash-R created in theirs: take theirs
------- hash-L ------- created in ours: take ours
------- hash-L hash-R created in both: add/add conflict
(even if hash-L = hash-R)
hash-B ------- ------- deleted in both: delete
hash-B ------- hash-R deleted in ours: delete if
hash-B = hash-R, else conflict
hash-B hash-L ------- deleted in theirs: delete if
hash-B = hash-L, else conflict
hash-B hash-L hash-R maybe run low level merge
For this final case, we must now go back to the 3-way merge description in the git read-tree
documentation:
- if a file exists in identical format in all three trees, it will automatically collapse to "merged" state ...
That is, if all three hashes match, there's nothing to merge. Just drop the hash into stage zero and toss out stages 1-3.
- stage 2 and 3 are the same; take one or the other (it makes no difference - the same work has been done on our branch in stage 2 and their branch in stage 3)
If both branch tips match, what's in the base is irrelevant: our changes and their changes are the same changes, producing the same content, so just make that stage zero and resolve the file.
Next, we have the two rules that cause fancy merge drivers to break. These are:
- stage 1 and stage 2 are the same and stage 3 is different; take stage 3 (our branch in stage 2 did not do anything since the ancestor in stage 1 while their branch in stage 3 worked on it)
- stage 1 and stage 3 are the same and stage 2 is different take stage 2 (we did something while they did nothing)
The first of these two rules mean that your low level merge driver never runs. Git simply decrees that their changes override your lack-of-changes!
Git will run your merge driver only when all three hashes exist, and all three hashes differ. That is, Git must believe that low-level conflicts exist before it runs a merge driver at all.
I would argue that this is a (minor) bug: if you specified a fancy merge driver, it might be an "ours" or "theirs" style merge, and you might want it to run even if one of these last two rules tells Git that there is no low level conflict to resolve. But it's how Git works, at least through Git version 2.15.