FAQ & limitations

Does Git Why send my code anywhere?

No. Repository text is never sent to a model host; embedding runs in-process. The only network access is a lazy, checksummed download of model weights on first use. After that, it's fully offline. See Offline and privacy.

Why does it sometimes return something irrelevant?

Git Why has no refusal path: it always returns its n closest-ranked commits, even when nothing in history actually answers the question. On our own no-evidence test cases (queries describing a decision the fixture history never made), the tool still returned a full page of results every time — it surfaced something, not the reason, because no reason was recorded. Read the returned commit critically; a low-confidence match is still just a match.

Is this a blinded benchmark?

No, and we say so directly: the hand-authored real-repository cases (on expressjs/express and axios/axios) were written by the same system that built the tool. That's real-repository evidence, not an independently authored or blinded test set. See Benchmarks for the full caveat and numbers.

Which benchmark number should I believe?

The one in section 0 of the report: MRR 0.266, Hit@5 0.374, on 174 questions derived mechanically from six real repositories and then gated so that anything git log --grep or git log -S could already answer was thrown out.

Every other number in the report is easier, and each is easier for a reason worth knowing:

• The synthetic fixtures were generated by the same system that built the tool, and Hit@5 saturates on them at 100% for every retrieval mode — which means Hit@5 stops discriminating there at all.
• The hand-authored real-repository set scores Hit@5 0.900 because the questions were written by someone who had already seen the commits.

Section 0 is lower than both because the questions are harder on purpose: no shared vocabulary with the commit, and no case that keyword search can reach. That is the regime this tool exists for, so it is the number that describes it.

Has an agent-usefulness study been run?

Yes — see section 5 of the report. Four arms (baseline, zg, both, git why) over the same frozen tasks, run across several models, with token counts reconciled against the provider's own accounting database and every comparison paired per task.

The short version: giving an agent git why reduced the tool calls it took to reach the answer, consistently in direction across models, at single-digit paired sample sizes per model. It is reported as descriptive, not significant, because that is what those sample sizes support.

git why --help says "no manual entry" — is that a bug?

It means the man page is not installed where man looks for it.

Git intercepts --help in the first position after any subcommand name (built in or external) and rewrites it to a man-page lookup before your subcommand ever runs. Verified with GIT_TRACE=1; this is Git's dispatch behaviour and an external subcommand cannot override it. Git Why ships git-why.1 for exactly this reason, and the install script copies it into place.

If you installed with plain npm install -g, npm 7 and later no longer link the man field, so the page ships inside the package but never reaches your MANPATH. Either use the install script, or copy it yourself:

cp "$(npm root -g)/@alliecatowo/git-why/man/git-why.1" \
   "$(npm prefix -g)/share/man/man1/"

git why -h and git-why --help work regardless, since neither goes through Git's man dispatch.

Does it work on Windows?

Not claimed. Support is macOS and Linux, arm64 or x64, Node >= 22.12. Use WSL2 on Windows.

What isn't indexed?

• Merge diff hunks (merge commits still contribute message, metadata, and first-parent changed paths).
• Binaries, lockfiles, minified artifacts, and confidently identified generated/vendored content (their commit summaries are still retained).
• Reflog-only objects, stash refs, notes, replace refs, and submodule history (a submodule is its own repository with its own index).

Full list: How it works — known coverage limits.

Where does state live, and how do I remove it?

Index state lives under your repository's Git common directory (so worktrees share one index); model weights live in a user-level cache outside any repository. Exact paths and uninstall steps are in docs/install.md.