ADR-0002 · One build-time git index instead of one walk per page

Status: Accepted, 2026-10-10.

Context

getGitMeta ran git log --follow per page plus three more git commands. The consuming site measured about 90 seconds for 303 pages and turned history off.

Decision

The first call builds one index for the content roots from a single git log --name-status -M, one git status and one git ls-files, resolving renames newest to oldest. Every page is answered from memory. The rows are cached by HEAD and reused while HEAD does not move. Paths outside the roots and index: false keep the per-path walk. GitLab enrichment reuses the local commits when the GitLab ref is the local history.

Why

Build time must not grow with page count. The index gives the same answers as the walk (verified on 120 pages of a 1000-commit repository) at a constant number of git commands.

Consequences

A build runs seven git commands cold and six warm. A filesystem-only signature rebuilds the index when the repository changes mid-process, so callers that commit or edit during a run still see current state.

Evidence

e949e7e, bf06ce5, c2d2a5c; npm run bench:history, test/git-index.test.js, test/gitlab-index.test.js.

Revisit when

Content arrives without a git checkout (see TD-003), or --follow semantics are needed for heavily edited renames.