git-trace

Git history visualizer for the AI coding era.

Quick Start

import { Trace } from 'git-trace'

<Trace commits={commits} autoPlay interval={2000} />

Props

Prop	Type	Default	Description
commits	Commit[]	[]	Array of commits
autoPlay	boolean	false	Auto-play through commits
interval	number	2000	Ms between commits
onCommit	(commit) => void	—	Callback on commit change
className	string	—	CSS class for root element
theme	Theme	'dark'	Color theme
filterable	boolean	false	Enable filter/search UI
defaultFilter	FilterOptions	{}	Initial filter state
onFilterChange	(filter) => void	—	Callback when filter changes

Commit Type

type Commit = {
  hash: string
  message: string
  author: string
  authorType: 'human' | 'ai'
  time: string
  lines: DiffLine[]
}

type DiffLine = {
  type: 'add' | 'remove' | 'ctx'
  content: string
}

Filtering

Enable the filter UI with filterable={true}:

import { Trace } from 'git-trace'

<Trace
  commits={commits}
  filterable={true}
  onFilterChange={(filter) => console.log(filter)}
/>

FilterOptions:

type FilterOptions = {
  search?: string          // Search in message, author, hash
  authorType?: 'all' | 'human' | 'ai'
  dateFrom?: string        // ISO date string (future)
  dateTo?: string          // ISO date string (future)
}

Programmatic filtering:

const [filter, setFilter] = useState({ authorType: 'ai' })

<Trace
  commits={commits}
  filterable={true}
  defaultFilter={filter}
  onFilterChange={setFilter}
/>

CLI

# Local git history to JSON
npx git-trace src/App.tsx --last 8 --json > commits.json

# Standalone HTML
npx git-trace src/App.tsx --last 8 --output embed.html

# Fetch from GitHub (cached 24h)
npx git-trace owner/repo src/path.ts --token $GITHUB_TOKEN

# Cache management
npx git-trace cache           # Show cache info
npx git-trace cache clear     # Clear cache

Configuration

Create .tracerc in project root or ~/.tracerc:

{
  "aiPatterns": {
    "emails": ["noreply@cursor.sh", "claude@anthropic.com"],
    "messages": ["Co-Authored-By: Claude", "AI-generated"],
    "logins": ["bot", "dependabot"]
  },
  "defaults": {
    "last": 10,
    "autoPlay": false,
    "interval": 2000
  },
  "cache": {
    "enabled": true,
    "ttl": 86400000
  }
}

Syntax Highlighting (Optional)

// Core: ~3.6KB gzipped
import { Trace } from 'git-trace'

// With syntax highlighting: +6KB
import { Trace } from 'git-trace'
import 'git-trace/highlight'

License

MIT