Git History Archaeologist
Answer "why is this code like this" with evidence from history. Never guess a motive the commit does not state.
Procedure
Pick the question type, then follow that path.
"Why does this line exist?"
git blame -w -C -L <start>,<end> <file>on the exact lines.-wignores whitespace-only changes;-Cfollows code moved from other files.- For the commit blame returns, read it in full:
git show <sha>. - Read the commit message and the surrounding diff. The why is usually in the message body or in a linked issue number.
- If the message is empty or unhelpful, widen:
git log -p -L <start>,<end>:<file>shows every change to those lines over time.
"When did this behavior change?"
git log -S "<string>" --oneline -- <file>finds commits that added or removed an exact string (the pickaxe). Use-G"<regex>"for a pattern.- Order the results oldest to newest. The oldest commit in the range is the introduction point.
- Read that commit with
git show.
"Which commit introduced this bug?"
- Confirm the bug is reproducible, and find a command or test that passes on a good commit and fails on the current one. Bisect needs this.
git bisect start, thengit bisect bad(current) andgit bisect good <known-good-ref>.- At each step, run the check and report
git bisect goodorgit bisect bad. If a step cannot be tested, usegit bisect skip. - When bisect names the first bad commit, run
git bisect resetand readgit showon that commit. - Report the commit, its author and date, and the specific hunk most likely responsible.
"What is the history of this file or function?"
git log --follow --oneline -- <file>to survive renames.- For a function, use
git log -L :<funcname>:<file>to follow just that function. - Summarize the arc: created, major rewrites, ownership changes.
Reporting format
- State the answer first: the commit, the date, the author.
- Quote the commit message line that supports the why. If the message does not state a reason, say "the commit does not record a reason" instead of inferring one.
- List the commands you ran so the user can reproduce the finding.
- Separate evidence from inference. Label any inference as such.
Boundaries
- Read-only. Do not reset, rebase, amend, or force-push.
- Never attribute intent that the commit message or diff does not support. "The author likely wanted X" is a guess; write it only with that wording and only when the diff strongly implies it.
- If blame points at a mass reformat commit, use
-wand-Cand try again before reporting it.
Supporting file
references/investigation-playbook.md has the full command reference, including git log search flags, git rev-list, and bisect edge cases.