메뉴
Use `git log`, `git blame`, and `git bisect` to track down when a regression was introduced or why a line of code looks the way it does. Use when the user asks "when did X break?", "who wrote this?", "find the commit that introduced Y", or any historical inquiry about the codebase.
| name | git-investigation |
| description | Use `git log`, `git blame`, and `git bisect` to track down when a regression was introduced or why a line of code looks the way it does. Use when the user asks "when did X break?", "who wrote this?", "find the commit that introduced Y", or any historical inquiry about the codebase. |
| license | MIT |
| metadata | {"author":"yottacode"} |
The repository history is the single best source of truth for "why is this code shaped this way?" and "when did this break?" Don't guess from the code alone — the commit that introduced a change usually explains it in the message.
Read-only git operations are available as dedicated tools:
git_log_file — commit history for a single file (with --follow across renames)git_blame_lines — per-line authorship for a line rangegit_show_file_at_rev — file contents at a specific commitgit_diff_files — diff between two refsgit (unified) — read-only subcommands auto-execute; log, show, bisect, etc.| Question | First tool |
|---|---|
| "When did line N change?" | git_blame_lines path:N..M |
| "What's the history of this file?" | git_log_file |
| "Find the commit that broke X" | git bisect — see §3 |
| "Diff between branches" | git_diff_files |
| "Show me the file at commit Y" | git_show_file_at_rev |
| "Find a commit by content" | git log -S '<string>' (pickaxe) |
| "Find a commit by message" | git log --grep '<pattern>' |
The pickaxe (-S) is the most powerful and most under-used flag. It finds commits where the count of <string> in any file changed — perfect for "when did someone add this method call?" or "who deleted this constant?".
git blame shows who last touched a line. That's not necessarily who wrote the logic — a whitespace fix or a rename can rewrite the blame line.
git blame -w ignores whitespace-only changes.git blame -M follows code movement within a file.git blame -C follows code copied/moved across files (slow on big repos).git blame --since=2.years.ago skips ancient commits.When the blame points to a "noisy" commit (mass refactor, formatter run), follow the chain backwards: git log <sha>^ -- <path> to see what came before, then re-blame at that revision: git blame <sha>^ -- <path>.
Bisect is the right tool when a test or behavior was working at commit A, is broken at commit B, and the commit set between them is too large to read.
git bisect start
git bisect bad <known-bad-ref, often HEAD>
git bisect good <known-good-ref>
# git checks out the midpoint; run your test
go test ./... -run TestX
# if it fails:
git bisect bad
# if it passes:
git bisect good
# repeat until git reports "<sha> is the first bad commit"
git bisect reset
Automate when you can:
git bisect run go test ./... -run TestX
git bisect run returns when the first bad commit is found; the script's exit code drives the verdict (0 = good, non-zero = bad, 125 = skip).
Edge cases:
exit 125 so bisect skips them rather than marking them bad.The default git log is too verbose for an agent to consume. Always shape it:
git log --oneline -20 # recent commits, terse
git log --oneline --grep='auth' # by message
git log --oneline -S 'oldFunctionName' # pickaxe
git log --oneline --since=1.month --author=alice # by date + author
git log --follow -p -- path/to/file # full history of one file, with patches
git log <branch>..HEAD --oneline # commits on HEAD not in <branch>
git log -L :functionName:path/to/file # history of a single function (heuristic, language-aware)
-L :functionName:path is magic when it works — it tracks one function across renames and refactors. Worth trying before reaching for blame.
When you find the commit that introduced an issue:
Example:
The break came in
a1b2c3d("auth: normalize email casing on lookup", 2025-08-14). It lower-cases the email in theWHEREclause, which doesn't match the historical mixed-case rows. The original code is from9f8e7d6(2023-01-04). A partial fix landed in4d5e6f7(2025-08-20) but didn't backfill the table.
Never say "git blame says X" — translate the SHA into the human story behind the change.
commit, reset, push, rebase) during an investigation. Those are separate tasks; ask first.-w and a follow-up check on noisy refactors.Pre-plan design interview. Use when the user asks for a feature or change and the right shape isn't obvious yet — before writing-plans, before code. Surfaces requirements, constraints, and trade-offs so the eventual plan rests on a real spec.
Capture the *why* behind decisions as you ship — ADRs for choices that are expensive to reverse, why-comments for non-obvious code, and rules files that stay current. Use when making an architectural decision, changing a public API, or when you've had to explain the same thing twice.
Real-engineer debugging loop — reproduce, minimise, hypothesise, instrument, fix, regression-test. Use when the user reports "X is broken", "this used to work", "I'm getting error Y", or any unexplained failure. Replaces shotgun-debugging with a disciplined cycle.
Review a Dockerfile (or Containerfile) for correctness, layer caching, multi-stage opportunities, image size, security, and reproducibility. Use when the user asks "review my Dockerfile", "why is my image so large?", or "is this Dockerfile good?".
Execute an approved plan step-by-step with checkpoints, batched edits, and visible progress. Use when a plan has been approved and you're about to start implementing, or when the user says "go ahead with the plan", "implement it", or hands you a checklist of steps.
Generate a concise handoff document that a fresh agent (or the same agent in a new session) can use to pick up where the current one left off. Use when the user asks to "summarize where we are", "make a handoff", "compact context before /clear", or any session-transition request.