🔍 Git Unearth

AI-powered git blame enhancer — understand WHY code was written, not just WHO wrote it. Semantic code unearth via Claude Code Skill.

中文文档

🎯 The Problem It Solves

| Scenario | Traditional git blame | Git Unearth | |----------|----------------------|-------------------| | "Why this line?" | alice 2024-06-15 — tells you who, but not why | Traces commit → PR → Issue → business context | | "Why this pattern?" | No insight | Groups related commits, identifies decision points | | "Was this intentional?" | Unknown | Confidence levels: 🟢 High (documented) 🟡 Medium (clear commit) 🔴 Low (AI inference) |

Core insight: Code unearth requires understanding decision history, not just author history.

✨ Core Features

🔍 Git Data Collection Layer (v0.1.1)

Structured parsing of git command output:

• collectBlame() — Line-level blame with commit metadata
• collectLog() — Commit history with RS/US delimiter parsing
• collectDiff() / collectDiffBetween() — Unified diff with hunks
• collectFollow() — File rename tracking
• collectCommitDetail() — Full commit + diff in one call

💾 Three-Tier Caching

Session (Map) → Filesystem → None. Avoid redundant git operations.

🧠 Semantic Analysis (v0.2.0+)

• Commit grouping (merge/PR/time window)
• Intent classification (feat/fix/refactor/perf/workaround)
• Decision timeline construction

🔄 Interactive Unearth Commands

| Command | Description | |---------|-------------| | /why <file:line> | Why was this code written? Trace decision history | | /history <path> | Evolution timeline with key decision points | | /context <hash> | Related changes network | | /decisions [area] | Architecture Decision Records from git history | | /unearth <area> | Deep interactive investigation |

🚀 Getting Started

Option 1: Claude Code Plugin (Recommended)

This project is a Claude Code Plugin. Install via marketplace for one-click setup.

Method A: Plugin Marketplace (Recommended)

# In Claude Code, run:
/plugin marketplace add saqqdy/git-unearth
/plugin install git-unearth

Method B: Local Install

# 1. Go to your project
cd your-project

# 2. Install npm package
pnpm add -D git-unearth

# 3. Copy plugin files
mkdir -p .claude/skills
cp -r node_modules/git-unearth/.claude/skills/git-unearth .claude/skills/

Available Commands

Type these commands in Claude Code:

| Command | Description | Example | |---------|-------------|---------| | /why | Why was this code written? | /why src/index.ts:42 | | /history | Evolution timeline | /history src/components/ | | /context | Related changes network | /context HEAD | | /decisions | Architecture Decision Records | /decisions | | /unearth | Deep interactive investigation | /unearth src/ |

Output Example

/why src/utils/format.ts:32

🔍 Analyzing `formatDuration()` ...

📖 Reason Trace:
  1. [2024-06-10] Add formatDuration helper (def456)
     → Shared time formatting across reporters
  2. [2024-06-05] PR #42 → Issue #18
     → User reported unfriendly time display

💡 Conclusion: Utility function added for consistent time display (🟢 High confidence)

💭 Follow up:
   - /history src/utils/format.ts
   - /context def456

Option 2: Programmatic Usage

pnpm add git-unearth

import {
  collectBlame, collectLog, collectCommitDetail, collectFollow,
  createCacheStore,
} from 'git-unearth'

const cache = createCacheStore({ sessionCache: true, fsCache: true })

// Get line-level blame
const blame = await collectBlame({
  root: process.cwd(), file: 'src/index.ts', startLine: 1, endLine: 10, cache,
})

for (const line of blame.lines) {
  console.log(`${line.line}: ${line.commit.message} (${line.commit.author.name})`)
}

// Get commit history
const log = await collectLog({
  root: process.cwd(), log: { maxCount: 20, paths: ['src/'] }, cache,
})

// Full commit detail
const detail = await collectCommitDetail({
  root: process.cwd(), hash: log.commits[0].hash, cache,
})

console.log(`${detail.commit.message}`)
console.log(`+${detail.diff.totalAdditions}/-${detail.diff.totalDeletions}`)

Option 3: CLI (Zero-Install)

# In any git repo, run directly:
npx git-unearth blame src/index.ts
npx git-unearth log --max-count 5
npx git-unearth diff abc1234
npx git-unearth follow src/index.ts
npx git-unearth detail abc1234
npx git-unearth help

Option 4: Clone and Run Examples

git clone https://github.com/saqqdy/git-unearth.git
cd git-unearth
pnpm install

# Run examples
npx tsx examples/basic-usage.ts
npx tsx examples/with-cache.ts
npx tsx examples/skill-commands.ts

📋 Version Roadmap

| Version | Codename | Theme | Status | |---------|----------|-------|--------| | v0.1.0 | Daybreak | Data collection layer (released) (blame/log/diff/follow + cache) | ✅ Current | | v0.2.0 | Sunrise | Analysis engine (commit grouping + intent classification) | 📋 Planned | | v0.3.0 | Dawn | Decision timeline + ADR generation | 📋 Planned | | v0.4.0 | Ember | Interactive unearth wizard | 📋 Planned | | v1.0.0 | Lighthouse | Production-ready + marketplace | 📋 Planned |

🗂️ Project Structure

git-unearth/
├── .claude/skills/git-unearth/   # Skill prompts (core product)
│   └── skill.md                        # Commands + execution flow
├── src/                                # TypeScript source
│   ├── index.ts                        # Public API exports
│   ├── types.ts                        # Core types
│   ├── errors.ts                       # GitCommandError, GitParseError
│   ├── collectors/                     # Git data collectors
│   │   ├── git-blame.ts                # Line-level blame
│   │   ├── git-log.ts                  # Commit history
│   │   ├── git-diff.ts                 # Unified diff
│   │   ├── git-follow.ts               # Rename tracking
│   │   └── git-cache.ts                # Three-tier cache
│   └── utils/                          # Utilities
│       ├── config.ts                   # Config management
│       └── format.ts                   # Output formatting
├── examples/                           # Usage examples
├── docs/                               # VitePress docs
└── internal/                           # Planning docs

🛠️ Development

pnpm install          # Install dependencies
pnpm run lint         # ESLint + auto-fix
pnpm run typecheck    # TypeScript check
pnpm run test         # Run tests (vitest)
pnpm run build        # Build (ESM + CJS)
pnpm run docs:dev     # Start docs server

🆚 Comparison

vs git blame

| Dimension | git blame | Git Unearth | |-----------|-----------|-------------------| | Output | author date code | Structured CommitInfo + evidence chain | | Why? | ❌ No | ✅ Trace PR/Issue/business context | | Grouping | ❌ No | ✅ Commit groups, decision points | | Confidence | ❌ No | ✅ 🟢🟡🔴 levels | | Caching | ❌ No | ✅ Three-tier cache |

📄 License

MIT