git diff/show/log route by predicate set membership, where git resolves output shape by suppressor recency plus a precedence lattice

[KuSh]

run_diff, run_show and run_log decide between three output routes — raw passthrough, RTK's compacted diff, and summary-only — by asking a set of per-token predicates "does any token match", at three separate call sites. git does not work that way, and the mismatch has been the single most productive source of regressions in the arg_tokenizer work (#3681): most review rounds there found at least one, and they were all the same shape — a flag combination taking the wrong route.

Filing the measurements rather than the fix, because the fix belongs on develop after #3681 lands (that PR is what introduced most of these predicates, so doing it before would mean rewriting code that does not exist here yet).

Measured semantics

Probed against git 2.53, LC_ALL=C, in a repo with a modification, a staged create, a rename, a delete, a binary file and a merge commit. Every flag singly across diff/show/log, then all 272 ordered pairs per subcommand.

Result 1 — only suppressors are order-sensitive. 40 ordered pairs per subcommand change shape when reversed, and every one of them has -s or --no-patch on one side. Identical across all three subcommands:

-s -p            = PATCH      -p -s            = NONE
-s --stat        = STAT       --stat -s        = NONE
-s --numstat     = NUMSTAT    --numstat -s     = NONE
-s --raw         = RAW        --raw -s         = NONE
--no-patch -U0   = PATCH      -U0 --no-patch   = NONE

Result 2 — --quiet is not one of them. Zero order-sensitive pairs. It loses to any shape request from either side and suppresses only when nothing else asked for output. Modelling it as a third spelling of -s silently dropped patches; fixed in #3681, but it is the clearest example of the class.

Result 3 — "last flag wins" is wrong for shape-vs-shape. I tested that model against 343 random 2–4 flag combinations: it predicts 207. Since two shape flags are never order-sensitive (Result 1), what git applies among them is a fixed precedence, not recency:

--name-only --compact-summary            -> NAMES   (not STAT)
--patch-with-stat --numstat --compact-…  -> PATCH   (not STAT)
--numstat -W --compact-summary           -> NUMSTAT (not STAT)
--check --raw --shortstat                -> NONE    (not STAT)

So the real model is two rules, not one:

• suppressor vs shape → last one wins
• shape vs shape → fixed precedence, order-independent

Neither is expressible as "does any token match this predicate", which is why each new flag combination has had to be discovered empirically.

Suggested shape of the fix

Fold the tokens once into an output shape, and let the three call sites read the result instead of each re-deriving it:

enum OutputShape { Patch { unified: Option<u32> }, Stat, NumStat, Raw, Names, None, Unparseable }

fn output_shape(sub: Subcommand, tokens: &[Token]) -> OutputShape

Each flag classifies as Suppressor, Sets(shape) or Inert — data, not control flow — and the precedence lattice among Sets is a table derived from the probe above rather than from reading documentation. Unparseable covers the flags that re-shape the columns the compaction keys on (--line-prefix, --output-indicator-*, word diff) and therefore have to take the raw route; note the probe classifier independently rediscovers this, since --line-prefix=X stops matching as a patch.

Before implementing, the precedence lattice needs measuring properly — the four rows above are a refutation of the simple model, not a complete ordering. That measurement is most of the work and is what makes this worth doing as its own change with its own verification budget.

Verification available

The differential harness used for #3681 compares real git / develop / branch across randomised flag combinations on exit code, first stderr line, and body presence, and it is what caught the --quiet case. Any implementation here should have to pass it with zero divergences that are not improvements — that is a much stronger gate than unit tests over the individual predicates, which reported green for every one of these regressions.

[KuSh]

Measured the lattice. There isn't one — the "fixed precedence" in the issue body above is wrong, and so is the enum OutputShape I proposed. Correcting both, with the model that does hold.

Method

git 2.53, LC_ALL=C, in a fixture with a modification, a large modification, a create, a delete, a rename, a binary change, whitespace errors (so --check fires) and a directory change above the dirstat threshold (so --dirstat fires) — the earlier probe reported three flags as producing nothing, which was the fixture, not git.

Each flag is fingerprinted by the features its output contains (hunk headers, stat bars, the N files changed line, numstat columns, raw :100644 lines, (new)/(gone) compact markers, dirstat percentages, create mode summary lines, word-diff [-…-]{+…+} markers) rather than by a single category, so --stat / --shortstat / --compact-summary are distinguishable instead of collapsing into one bucket. Then: all 120 unordered setter pairs, then 1,200 random 2–6 flag combinations to test candidate models.

What the pairs show

• Order-sensitive setter pairs: 0. With a fine-grained classifier as with the coarse one, no two shape flags change the result when swapped.
• 46 of the unambiguous pairs compose — the result is the union of both flags' features. -p --stat prints the stat and the patch. They do not compete at all, which is why no precedence shows up.
• 3 pairs are mutually exclusive and git refuses them outright (128): --name-only+--name-status, --name-only+--check, --name-status+--check — the "cannot be used together" family, which also includes -s.
• 26 pairs are indistinguishable because one flag's features are a superset of the other's; nothing in the data requires precedence to explain them.

The model that holds: 1,073 / 1,077

Three classes and an ordered fold with a latch. Validated on 1,200 random 2–6 flag combinations across three seeds (123 refused by git, excluded):

EXCLUSIVE  --name-only  --name-status  --check
           latches: everything after it is ignored, and it wins over everything before

ADDITIVE   -p  -U<n>  --stat  --shortstat  --compact-summary  --numstat  --raw
           --dirstat  --summary  --patch-with-stat  --patch-with-raw  --binary
           accumulates: each adds its own shape to what is already there

SUPPRESS   -s  --no-patch
           resets the accumulator to empty and clears the exclusive latch

MODIFIER   --word-diff, and --compact-summary's rendering half
           changes how a shape renders, contributes nothing on its own,
           and is NOT cleared by a suppressor

acc, latched = None, False
for f in flags:
    if   f in SUPPRESS:                   acc, latched = empty, False
    elif f in EXCLUSIVE:                  acc, latched = shape_of(f), True
    elif f in ADDITIVE and not latched:   acc = (acc or empty) | shape_of(f)
return default_for(subcommand) if acc is None else acc

Worked examples, all measured:

--stat --patch-with-raw -U0 --check --raw   -> check only      (latch; --raw after it ignored)
--name-status --stat -s --shortstat -p      -> shortstat+patch (-s cleared the latch)
-p --patch-with-stat --shortstat --no-patch --numstat  -> numstat only  (reset)
--compact-summary -s --stat                 -> stat, rendered compact   (modifier is sticky)

The four misses out of 1,077 are all the last line: --compact-summary before a suppressor still tints a later --stat with (new)/(gone). Confirmed directly — --compact-summary -s --stat keeps the markers, -s --stat does not — so modelling the modifier half as sticky takes the model to complete.

--quiet is absent from all four classes, and order-sensitive in zero pairs, which is the same conclusion the fuzzing reached independently.

Two corrections to this issue

1. "Fixed precedence lattice" was wrong. There is no ordering among shape flags because they mostly do not compete — they accumulate. What produced the earlier 207/343 was a last-wins model applied to flags that compose. Only three flags dominate, and they do it absolutely rather than by rank.

2. enum OutputShape was wrong, and in a way that matters. Since shapes accumulate, git diff -p --stat --raw emits three of them at once. A single-valued enum cannot represent that, so the fix wants a set — struct OutputShape { patch: bool, stat: Option<StatKind>, numstat: bool, raw: bool, names: Option<NameKind>, … } — folded as above. This is the same mistake the current predicates make: RTK picks one route where git may be emitting several shapes together, which is why combinations rather than single flags have been where the regressions live.

That second point is the real argument for doing this: it is not that the current code has the precedence wrong, it is that "which one route" is not a question with an answer for a third of these commands.