---
name: git-log-forensics
description: Reading a repository's history to find when behaviour changed and why, rather than guessing from the current tree.
when_to_use: You are investigating why code is the way it is, or when a behaviour was introduced.
tags: [analysis, git]
---

# The history answers questions the tree cannot

The current tree shows what is true. It does not show what was tried, what was
reverted, or which line was load-bearing enough to be touched forty times.

## The four commands that answer most questions

```bash
git log -S'<string>' --oneline -- <path>     # when did this string appear/vanish
git log -L'<start>,<end>:<file>'             # every change to these lines
git log --follow -- <file>                   # survives renames
git bisect start <bad> <good>                # find the commit that changed it
```

`-S` (the "pickaxe") is the most under-used and the most powerful: it searches
for commits where the *count* of a string changed, so it finds the commit that
introduced a call, not every commit that mentions it. `-L` gives the biography
of a specific function.

## Churn marks risk

```bash
git log --format= --name-only | sort | uniq -c | sort -rn | head -20
```

Files at the top are either the project's core or its problem area, and the
commit messages tell you which. A file changed in 200 commits by 15 authors is
where the next bug will be, whatever the current code looks like.

## Read the message, then distrust it

A commit message states intent. The diff states what happened. When they
disagree — "small refactor" touching thirty files, "fix typo" changing a
condition — the diff is the truth, and the disagreement is itself a finding
worth recording.

## Blame points at the last toucher, not the author

`git blame` shows who last modified a line, which after a reformat, a rename or
a lint pass is whoever ran the tool. Use `-w` (ignore whitespace) and
`-C` (detect moved code) before drawing any conclusion, and prefer `log -L` when
you want the line's history rather than its current owner.

## What to report

A forensic finding is a commit hash, a date, and the reason the change was made
if the message or its PR gives one. "This check was added in `a1b2c3d` after an
incident" is actionable. "This code looks defensive" is not.