git-archaeology

Git Archaeology Methodology

Extract behavioral intelligence from version control history. Commit messages, PR descriptions, blame annotations, and issue references encode design decisions, behavioral changes, and maintenance patterns that no other source captures.

When to Use This Mode

Git archaeology activates when:

• The target is a git repository (or has a .git directory)
• The discovery inventory identifies a git repository with meaningful commit history
• Other modes discover a git repository during analysis

This mode runs independently of all other intelligence sources. It requires only access to the git repository and optionally to a GitHub/GitLab remote. All output is RAW (commit messages and PR descriptions may reference proprietary internals).

Why Git History Matters

Source code tells you what the system does NOW. Git history tells you:

• What changed and why -- commit messages encode intent that is invisible in the current code
• What broke and how it was fixed -- fix commits reveal failure modes and edge cases
• What was deliberately removed -- reverted features and deleted code reveal abandoned behaviors
• Where maintenance concentrates -- frequently modified files signal complexity and instability
• What decisions were debated -- PR descriptions capture design trade-offs that never appear in documentation

Phase 1: Repository Overview

Goal: Establish the scope, age, and shape of the project.

# Commit count and date range
echo "Total commits: $(git rev-list --count HEAD)"
echo "First commit: $(git log --reverse --format='%ai' | head -1)"
echo "Latest commit: $(git log -1 --format='%ai')"

# Contributors
git shortlog -sn --no-merges | head -20

# Active branches
git branch -r --sort=-committerdate | head -20

# Tags (releases)
git tag --sort=-version:refname | head -20

# Commit frequency (commits per month, last 12 months)
for i in $(seq 0 11); do
  month=$(date -d "$i months ago" +%Y-%m 2>/dev/null || date -v-${i}m +%Y-%m)
  count=$(git rev-list --count --after="${month}-01" --before="${month}-31" HEAD 2>/dev/null || echo "0")
  echo "$month: $count"
done

# Top-level directory structure at HEAD
git ls-tree --name-only HEAD