git-archaeology

Git archaeology

Finding out why, before you change it.

Why this exists

An FDE reads a lot of code that looks wrong. Some of it is. Much of it is an incident fix, a regulatory requirement, a workaround for a downstream system's bug, or a special case for one customer worth more than the rest combined.

The odd-looking code is odd because something happened. Removing it re-creates whatever it was preventing — usually silently, usually in production, and usually with your name on the commit.

You are the person least equipped to tell the difference. The permanent team carries the scar tissue; you don't. History is how you acquire it in three minutes instead of three years.

When this applies

• Code looks unnecessary, bizarre, or over-complicated
• Before deleting anything you don't understand
• A magic number or special case with no explanation
• A comment that contradicts the code
• You're about to say "this can be simplified"
• A [confirmed] claim you want to upgrade with the reasoning behind it

When it doesn't

• Code you already understand
• Genuinely new code with no history
• You need runtime behavior rather than intent — that's trace-the-flow
• Shallow clone with no history — say so and tag conclusions [unverified]

Prerequisites

Git history you can read. If git rev-parse --is-shallow-repository is true, stop and tag any intent claim [unverified]. Locate the workspace so the write-up lands with the rest of the engagement.

Procedure

1. Blame the specific lines

git blame -L 88,120 path/to/File.java
# Follow through moves and reformatting, which otherwise hide the real author
git blame -w -C -C -L 88,120 path/to/File.java

-w ignores whitespace changes, -C -C follows code moved between files. Without them, blame frequently points at whoever last reformatted the file, which tells you nothing and wastes the step.

2. Read the whole commit, not just the line

git show <sha>
git show <sha> --stat