Git Why

git blame tells you who changed the code. git why finds the history that explains it.

Local-first semantic + full-text search over Git history. It returns the actual commit, its author's real words, and the relevant diff. It retrieves evidence; it does not generate an explanation of its own.

Real output from mise run demo, which rebuilds a small fixture repository from bench/fixtures/demo/build.mjs and runs these two queries against it. Nothing here is hand-written, and you can reproduce it in one command.

For output against real repositories — curl, zod, redis — including a worked case where this is the wrong tool, see docs/examples.md or the recorded terminal sessions.

$ git why "that bizarre bug where reconnecting subscribed twice"

1. 7deab42  Stop duplicate subscriptions after reconnect
   2025-11-20 · Maya Chen

   Reconnecting re-ran the subscribe handler without clearing the previous
   registration, so every reconnect doubled the delivered events.

   src/net/socket.ts
   -export function connect(url) { return new Socket(url); }
   +export function connect(url) {
   +  const s = new Socket(url);
   +  s.on('reconnect', () => resubscribeOnce(s));
   +  return s;
   +}

$ git why "why do we keep the session when the refresh token is empty?"

1. f17db20  Fix infinite token-refresh loop
   2025-11-03 · Maya Chen

   Provider X can return an empty refresh token while the current access
   token remains valid. Retrying here puts clients into an infinite loop.

   src/auth/refresh.ts
    export function refresh(session, refreshToken) {
   -  if (!refreshToken) throw new InvalidTokenError();
   +  if (!refreshToken) return session;
      return exchange(refreshToken);
    }

Install

Install from npm (Node >= 22.12):

npm install -g @alliecatowo/git-why

Or with Homebrew (macOS and Linux; pulls in node):

brew install alliecatowo/tap/git-why

Or build from source:

git clone https://github.com/alliecatowo/git-why.git
cd git-why
npm ci
npm run build
npm install -g .

The package installs a git-why executable, which Git dispatches as the subcommand git why. No alias setup needed. More install paths — pinned versions, a GitHub release tarball, building from source, uninstalling — are in docs/install.md.

First run

cd your-repo
git why "why do we retry twice before giving up"

The first query downloads a small embedding model (about 32 MB, checksum-verified, cached under ~/.cache/git-why/models) and indexes the repository's history into .git/why/; later queries are incremental. Behind a proxy or offline, see HTTPS_PROXY, GIT_WHY_MODEL_BASE_URL (mirror) and GIT_WHY_OFFLINE in docs/operations.md. git why status shows whether the index is current.

Use it with an agent

Two plugins ship in plugins/:

OpenCode users get opencode/ — an `openc

... View full README on GitHub