What do the Git “pairing broken” and “unknown” statuses mean, and when do they occur?

Question

Some options in git diff, for instance --name-status, cause the output of a status letter next to a file name. They are:

A, C, D, M, R, T, U, X, B

… and they mean

Added (A), Copied (C), Deleted (D), Modified (M), Renamed (R), type (i.e. regular file, symlink, submodule, …) changed (T), Unmerged (U), Unknown (X), or pairing Broken (B).

Question: how should the X and B statuses be interpreted, and which circumstances lead to their appearance? Can you provide a series of steps leading to such statuses appearing in the output of git-diff, and possibly ways to fix them?

Answer 1

The B “broken pair” status never appears directly in --name-status output, it is only useful as an argument to the option --diff-filter when also using the option -B (--break-rewrites). Using it as a filter selects files that have had at least a certain percentage of their content deleted or changed.

This “breaking” is not be terribly useful with --name-status since the point of “breaking” is mostly to change how the diff text is generated: it eliminates context lines (unchanged lines) from the diff output instead of generating the add and remove lines that would be required around whatever “random” common subsequences the diff algorithm happened to find.

git init broken-pairs
cd broken-pairs
nums() { seq "$1" "$2" 2>/dev/null || jot $(($2 - $1 + 1)) "$1"; }
nums   0  99 > a
nums 100 199 > b
git add a b
git commit -ma=0-99,b=100-199
nums 200 299 > a
{ nums 100 149; nums 350 399; } > b
git diff --name-status --diff-filter=B             # selects nothing
git diff --name-status --diff-filter=B -B          #         M100    a
git diff --name-status --diff-filter=B -B/50       #         M100    a M050    b

---

The X “unknown” status should never actually appear. If it does appear, it means a pathname that is neither unmerged, added, deleted, modified or had its type changed (effectively: unchanged) unexpectedly made it to the core of the internal diff machinery; the error feeding unmodified <pathname> to diffcore will also be generated.

It appears to be left over from some old mode of operation.