git-chronicle

A CLI tool that indexes your git history into a searchable database and generates insights about your codebase.

Inspired by msgvault - applying the concept of archival + search + analytics to git repositories instead of messages.

Features

• Index any git repository into a local SQLite database
• Search commits by message, author, date range, or files changed
• Analyze contributor patterns, file hotspots, and activity timelines
• Report code velocity metrics and project health indicators
• Export data for visualization or further analysis

Installation

pip install git-chronicle

Or install from source:

git clone https://github.com/dabit3/git-chronicle.git
cd git-chronicle
pip install -e .

Quick Start

# Index the current repository
git-chronicle index

# Index a specific repository
git-chronicle index /path/to/repo

# Search commits
git-chronicle search "fix bug"

# Get contributor stats
git-chronicle stats contributors

# Find file hotspots (most changed files)
git-chronicle stats hotspots

# Activity timeline
git-chronicle stats timeline --period weekly

# Full project report
git-chronicle report

Commands

index

Index a git repository into the chronicle database.

git-chronicle index [PATH] [OPTIONS]

Options:
  --db PATH       Database file path (default: .git-chronicle.db)
  --since DATE    Only index commits after this date
  --branch TEXT   Branch to index (default: current branch)
  --all           Index all branches

search

Search indexed commits.

git-chronicle search QUERY [OPTIONS]

Options:
  --author TEXT   Filter by author
  --since DATE    Commits after this date
  --until DATE    Commits before this date
  --files TEXT    Filter by files changed (glob pattern)
  --limit INT     Max results (default: 20)

stats

Generate statistics about the repository.

# Contributor statistics
git-chronicle stats contributors [OPTIONS]
  --top INT       Show top N contributors (default: 10)
  --metric TEXT   Sort by: commits, additions, deletions (default: commits)

# File hotspots - most frequently changed files
git-chronicle stats hotspots [OPTIONS]
  --top INT       Show top N files (default: 20)
  --since DATE    Only consider commits after this date

# Activity timeline
git-chronicle stats timeline [OPTIONS]
  --period TEXT   Group by: daily, weekly, monthly (default: weekly)
  --author TEXT   Filter to specific author

# Code velocity
git-chronicle stats velocity [OPTIONS]
  --period TEXT   Analysis period: week, month, quarter (default: month)

report

Generate a comprehensive project report.

git-chronicle report [OPTIONS]
  --format TEXT   Output format: text, json, html (default: text)
  --output PATH   Write report to file

Example Output

$ git-chronicle stats contributors --top 5

Contributor Statistics
=======================

 Rank  Author              Commits   Additions   Deletions
--------------------------------------------------------------
 1     Alice Smith         234       +45,230     -12,450
 2     Bob Johnson         189       +32,100     -8,900
 3     Charlie Brown       156       +28,450     -15,200
 4     Diana Ross          98        +15,670     -4,230
 5     Eve Williams        87        +12,340     -3,890

Total: 15 contributors, 892 commits

$ git-chronicle stats hotspots --top 5

File Hotspots (Most Changed)
=============================

 Rank  File                          Changes   Last Modified
---------------------------------------------------------------
 1     src/core/engine.py            89        2 days ago
 2     src/api/handlers.py           67        1 week ago
 3     tests/test_engine.py          54        2 days ago
 4     src/utils/helpers.py          48        3 days ago
 5     config/settings.py            45        1 month ago

Database Schema

git-chronicle stores data in SQLite with the following tables:

• commits - Commit metadata (hash, author, date, message)
• files - Files changed in each commit with additions/deletions
• authors - Unique author information
• branches - Branch information and HEAD positions

Use Cases

• Onboarding: Quickly understand a new codebase's history and key contributors
• Code Review: Find who has expertise in specific files
• Project Health: Track commit velocity and contributor engagement
• Auditing: Search for specific changes or patterns in history
• Documentation: Generate activity reports for stakeholders

License

MIT