pip install diffstory
cd my-repo
diffstory --staged
# Opens a .html in your browser

Screenshots

Why DiffStory?

Reading a diff in your terminal works — until it doesn't.

DiffStory combines git diff, git blame, and git log into a single interactive HTML report — no server, no accounts, no data leaving your machine.

Features

Additional Capabilities

• Keyboard navigation — J/K to move between files, F or / to search, U/S/I to switch views
• Deep linking — #file-0 or #L-0-42 links to specific files and lines
• Binary file detection — Image previews and metadata placeholders
• Export formats — JSON, Markdown, and CSV alongside HTML (--json, --md, --csv)
• Review mode — Per-file checkboxes with localStorage persistence (--review)
• Config file — ~/.diffstory.toml or .diffstory.toml for persistent defaults
• Accordion sidebar — Click a file in the sidebar to focus it (expand clicked, collapse others); use Collapse All / Expand All to toggle globally
• Auto-update — Checks PyPI on startup and self-upgrades to the latest version transparently, so automation scripts always run the newest code. Disable with DIFFSTORY_DISABLE_AUTO_UPDATE=1

Installation

pip install diffstory

Requires: Python 3.10+ and Git.

From source:

git clone https://github.com/lakshayjindal/diffstory.git
cd diffstory
pip install -e .

Quick Start

# Working tree diff
diffstory

# Staged changes
diffstory --staged

# Commit comparison
diffstory HEAD~1 HEAD

# Branch comparison with path restriction
diffstory main feature/auth src/

# Custom output
diffstory -o report.html

# Generate from a diff file (no git repo needed)
diffstory --diff /path/to/patch.diff

# Multiple export formats
diffstory --staged --json --md --csv

What Makes DiffStory Different?

Screenshots and Walkthrough

Overview

The main report screen. A sidebar lists all changed files with add/delete counts. The diff content area renders each file with its full change history. The toolbar gives access to view switching, search, theme, statistics, and the file list.

Why it matters: You get the full context of a changeset in one view — no scrolling between terminal windows or switching between git diff and git blame.

Unified View

The default view. Lines are color-coded: green for additions, red for deletions. Line numbers for both old and new files are displayed side by side. Syntax highlighting is applied via Pygments.

Why it matters: Familiar to anyone who uses git diff, but with syntax highlighting and interactive features that the terminal cannot provide.

Side-by-Side View

Original file on the left, modified file on the right. Lines are aligned by position. Useful for understanding structural changes at a glance.

Why it matters: For large refactors or renames, seeing both versions side by side reveals patterns that a unified diff obscures.

Inline View

Word-level diffs. Instead of showing a removed line and an added line, changed words are highlighted inline — removed text is struck through in red, added text is highlighted in green.

Why it matters: When a single word changes on a long line, finding the difference in a unified diff requires careful scanning. The inline view makes it obvious instantly.

Blame Tooltip

Hover any changed line to see a tooltip with the author name, commit hash, commit subject, date, and relative time. Click the line to open a full commit detail drawer.

Why it matters: Answers "who wrote this line and why?" without leaving the report. No more switching to a terminal to run git blame.

Statistics Dashboard

A floating panel with file counts, add/delete deltas, author and commit counts, contributor breakdown, and a table of the most-changed files.

Why it matters: Gives an instant high-level summary of the changeset — useful for code reviews, release notes, and stakeholder updates.

Typical Use Cases

Architecture

diffstory/                      # PyPI package
├── cli.py                      # Argument parsing, orchestration
├── git_utils.py                # Git subprocess wrappers (diff, blame, log)
├── diff_parser.py              # Unified diff → structured data
├── syntax.py                   # Pygments syntax highlighting
├── html_generator.py           # Self-contained HTML generation
├── updater.py                  # Auto-update check against PyPI
├── loader.py                   # Spinner / progress utilities
└── generators/
    ├── get_css.py              # All CSS (inline)
    └── get_js.py               # All JavaScript (inline)

• Python 3.10+ — Only two runtime dependencies: Pygments (syntax highlighting) and build/twine (packaging).
• Git CLI — All Git operations go through subprocess. No GitPython dependency.
• Self-contained HTML — CSS, JavaScript, and data (blame, commits, search index) are embedded directly. No assets to serve, no network requests.
• Offline-first — Everything runs locally. Generated reports work without internet access, indefinitely.
• Auto-updating — On startup, diffstory checks PyPI for a newer version and upgrades itself automatically before running your command. No manual pip install --upgrade needed.

Philosophy

DiffStory is not trying to replace GitHub, GitLab, Bitbucket, or Git itself.

It exists to solve a specific problem: creating portable, shareable, interactive change reports that work anywhere, independent of infrastructure.

• Reports are static files. Open them in any browser. Email them. Archive them. Attach them to tickets.
• No accounts. No servers. No data leaves your machine.
• The report answers the five questions reviewers actually ask: What changed? Who changed it? When? Why? How did it evolve?

Roadmap

Ideas for future releases — nothing guaranteed:

• Annotations & comments — Inline commenting on specific lines, saved to the report
• PDF export — Print-quality report generation
• Diff comparison — Compare two reports side by side
• Plugin system — Custom analyzers and visualizations
• WebSocket live reload — Watch file changes and regenerate reports automatically
• Language-specific analysis — TypeScript type changes, Rust borrow checker impact, etc.
• Team review workflows — Aggregate reviews from multiple team members

Contributing

Contributions are welcome. The project is small and the codebase is straightforward.

• Issues — Bug reports, feature requests, and questions.
• Pull requests — Please open an issue first to discuss the change.
• Local development — pip install -e . for editable install. Run diffstory --staged in any repo to test.

git clone https://github.com/lakshayjindal/diffstory.git
cd diffstory
pip install -e .
diffstory --staged -o /tmp/test.html

License

MIT