Why your custom git merge driver did not run

You wrote merge=mydriver in .gitattributes, defined the driver, and git still stopped with a conflict. Or it did not stop, and a side of the merge is gone.

The documentation explains how to define a driver. It says less about the ways git will skip it. So we built the smallest driver we could, one that writes a line to a log every time git calls it and then keeps the lines of both sides, and ran it through 10 merges in throwaway repositories with plain git 2.39.5.

Git called it in 6. Here are the 4 where it did not, and the 2 surprises in the 6 where it did.

The 10 merges

Every case ran twice and printed the same thing both times. The script and its output are in this site's repository, linked at the end.

1. The clone never learned the driver

.gitattributes is a committed file, so it travels with the repository. The driver's definition does not. git's own manual is explicit that it lives in .git/config or ~/.gitconfig, and git never copies config on clone.

So in a fresh clone (case 2) the attribute says merge=keepboth, there is no keepboth to run, and git falls back to its normal text merge. Two branches that each appended a line got an ordinary conflict.

The trap is the diagnostic people reach for first. In that clone, git check-attr merge -- log.txt still answered merge: keepboth. It tells you the attribute is set. It does not tell you a driver exists. The command that does:

git config --get merge.keepboth.driver

It printed nothing.

This one bites anywhere a merge runs before your setup step: CI that checks out and merges, a teammate's first git pull, a new machine.

2. The command is not on PATH

This is the dangerous one. In case 3 the driver was defined, but git could not find the command. git printed one line, easy to miss in merge output:

keepboth .merge_file_… .merge_file_… .merge_file_…: keepboth: command not found
Auto-merging log.txt
CONFLICT (content): Merge conflict in log.txt

Then it marked the file as conflicted, which is correct. But the file had no conflict markers. It held our side and nothing else.

That follows from git's contract with a driver. The driver is handed our version as %A and is expected to overwrite it with the result, and a non-zero exit means "there were conflicts". A driver that never started never overwrote anything, and the shell's not-found status is non-zero. So git reports a conflict and leaves %A as it was.

The result is a conflicted file that looks resolved. Search it for <<<<<<< and you find nothing. Open it and it parses. git add it and the other side is gone. That is not hypothetical: yukineko/claude-harnesses#1293, opened on 2026-10-03, reports exactly this with a TOML task file, including the git add and commit that dropped the other branch's changes.

Two defences. Put an absolute path in merge.<name>.driver, or a wrapper in the repository that fails loudly. And when a merge stops, trust git diff --name-only --diff-filter=U over your eyes. It listed the file in case 3 when the content gave no sign.

3. The branch is older than the attribute

In case 4 the attribute was committed on main after branch old was cut. On old, before merging, git check-attr said merge: unspecified, and merging main into it (4a) gave a plain conflict. What 4a to 4c show is that the attribute counts only if the branch you are on already has it.

Merging the other way (4b), from main, called the driver and merged clean. So did merging main into old after first committing main's .gitattributes onto old (4c).

Two things make this one hard to see. "Update branch" on a pull request is exactly direction 4a. And after the failed merge, git check-attr on old reported merge: keepboth, because the merge had already brought .gitattributes into the working tree. Run the diagnostic after the fact and it tells you the driver was configured. paiml/aprender#3308 found the same thing and titled it well: the driver is retroactively inert for every pull request older than the declaration.

4. The merge happened on the server

We did not test this one, and are reporting it rather than confirming it. A driver is a command on your machine, so a merge button that merges on the host's servers has nothing to run. gitlab-org/gitlab#18830, still open, says GitLab reads union and binary from .gitattributes but not custom drivers, because those live in gitconfig. deep-code-review#862 reports the same of a hosted merge and recommends merging the base branch locally and pushing. If your driver is the only thing that makes a file merge, the host's "conflicts" badge is answering a different question.

Two that are not failures, and one that is worse

Case 5: only one branch changed the file, and the driver was not called. That is right. There was nothing to merge, so git took the changed side. If you are testing a driver, make both branches touch the file or you will think it is broken.

Case 7: git rebase and git cherry-pick both called the driver. A driver is not merge-only.

Case 6 is the one to read twice. Both branches changed the file, one at the top and one at the bottom. git's own text merge would have combined those without a conflict. Because the attribute names a driver, git called the driver instead, and our toy driver, which only knows how to keep lines from both sides, produced this, with exit 0:

top-a 1 2 3 4 5 6 bottom top bottom-b

No conflict, no warning, and a file that is wrong. A driver does not run after git fails to merge. It runs instead of git, on every merge where both sides touched the path. So it has to be at least as good as the text merge on the easy cases, not only the one you wrote it for. A keep-both driver like ours is only safe on files that are append-only, where every line is a whole record.

A four-line check

When a driver seems not to have run, these answer the four questions in order:

git check-attr merge -- path/to/file      # is the attribute set on this branch, now?
git config --get merge.NAME.driver        # does this clone define the driver?
command -v the-driver-command             # can git's shell find it?
git diff --name-only --diff-filter=U      # what git still counts as conflicted, markers or not

Run the first one before the merge, not after. Case 4a is why.

What this does not cover

• One machine and one git version: 2.39.5, Apple's build. Other versions may differ in what they print, and we did not check them
• One file, one line per branch, a driver we wrote to be simple. Real drivers do more and fail in more ways
• No hosted merge was run. Section 4 is other people's reports
• We did not test merge.<name>.recursive, %P or %L, or drivers that crash (git's manual says those should exit above 128 and are treated as a failure, not a conflict)