# gitstack
[](https://crates.io/crates/gitstack)
[](LICENSE)
> **Git history viewer focused on analysis and insights**
>
> *Built for the AI-assisted development era - optimized for Claude Code and similar tools*
Release history: see `HISTORY.md`.
To regenerate release history from git tags:
```bash
make history
```
## Why gitstack?
| lazygit | Git operations | Staging, rebasing, cherry-picking |
| tig | Log browsing | Quick commit viewing |
| keifu | Graph visualization | Beautiful branch display |
| **gitstack** | **Analysis & Insights** | **Understanding your codebase** |
gitstack answers questions like:
- *"Who has been working on this module?"*
- *"Which files are changed most frequently?"*
- *"Which commits had the biggest impact?"*
- *"Are there any stale branches that should be cleaned up?"*
- *"How healthy is this project overall?"*
## Install
```bash
cargo install gitstack
```
Or build from source:
```bash
git clone https://github.com/Hiro-Chiba/gitstack
cd gitstack
cargo install --path .
```
## Quick Start
1. **Install**: `cargo install gitstack`
2. **Launch**: `gitstack` (run in any git repository)
3. **Basic Operations**: Use `1`-`5` to switch panels, `Tab` to toggle focus, `?` for help, `.` for quick actions, `q` to quit
## Features
### Analysis Suite
Press a single key to get instant insights:
| `A` | Author Stats | Commits, lines added/deleted per author |
| `H` | Heatmap | Most frequently changed files |
| `. → T` | Timeline | Commit activity by hour/day |
| `. → O` | Ownership | Code ownership by file/directory |
| `. → I` | Impact Score | Commit impact scores (0.0-1.0) |
| `t` | Topology | Branch health and recommendations |
| `D` | Health Dashboard | Project health score (0-100) with alerts |
### Smart Filter
Powerful filtering with intuitive syntax:
```
/author:john # Filter by author
/since:7days # Recent commits
/until:2024-01-01 # Before date
/message:fix # Search commit messages
/file:src/main.rs # Commits touching specific file
/hash:abc123..def456 # Commit range
```
Combine filters: `/author:john since:1week file:*.rs`
### Dashboard Layout
A single unified dashboard with a sidebar and context-sensitive main panel:
```
┌──────────────────┬────────────────────────────────────────┐
│ 1 Status │ │
│ repo: gitstack │ │
│ branch: main ↑2 │ │
├──────────────────┤ │
│ 2 Commits │ Main Panel │
│ ● abc123 feat.. │ (context-sensitive view) │
│ ● def456 fix.. │ │
│ ◆ ghi789 merge │ Commits → diff/detail │
│ ○ jkl012 chore │ Branches → compare/topology │
├──────────────────┤ Files → patch/diff │
│ 3 Branches │ Stash → stash diff │
│ ● main │ Status → health dashboard │
│ feat/auth │ │
│ fix/bug-123 │ │
├──────────────────┤ │
│ 4 Files │ │
│ M src/main.rs │ │
│ A src/new.rs │ │
├──────────────────┤ │
│ 5 Stash │ │
│ stash@{0}: WIP │ │
└──────────────────┴────────────────────────────────────────┘
j/k:move Enter:detail 1-5:panel Tab:focus h/l:side/main ?:help q:quit
```
The sidebar contains five panels (Status, Commits, Branches, Files, Stash). Press `1`-`5` to switch between them. The main panel updates automatically based on which sidebar panel is active. Use `Tab` to toggle focus between sidebar and main panel, or `h`/`l` to move focus left/right.
When the Commits main panel is focused (`l` or `Tab`), use `j`/`k` to navigate through changed files, `Enter` or `Space` to expand/collapse individual file diffs, and `e`/`E` to expand/collapse all diffs at once.
### Branch Graph
Color-coded branch visualization with smart color assignment:
- Adjacent lanes never share the same color
- Branches from the same fork point get distinct colors
- Clear merge visualization with proper line connections
### Project Health Dashboard
Press `D` to see overall project health:
```
┌─ Health Dashboard ─────────────────────────────────┐
│ Overall Score: 78 / 100 (Good) │
│ ████████░░ │
│ │
│ Quality ████████░░ 82% │
│ Test Health ██████░░░░ 65% │
│ Bus Factor █████████░ 90% │
│ Tech Debt ███████░░░ 75% │
│ │
│ ⚠ Warning: 3 stale branches need attention │
│ ℹ Info: Test coverage could be improved │
└────────────────────────────────────────────────────┘
```
### Branch Recommendations
The Topology view (`t`) now shows recommended actions for each branch:
| 🗑 | Delete | Merged or inactive for 60+ days |
| ↻ | Rebase | Far behind main branch |
| ⤵ | Merge | Ready to merge (has commits ahead) |
| 👁 | Review | Long-lived branch needs attention |
### CLI Mode (Non-Interactive)
For AI coding assistants and scripting, gitstack provides JSON output:
```bash
gitstack --stats # Author statistics
gitstack --heatmap # File change frequency
gitstack --impact # Commit impact scores
gitstack --health # Project health score
gitstack --pack # AI-ready insight pack
gitstack --review-pack # AI review decision pack
```
> Full option list and examples: [docs/CLI.md](docs/CLI.md)
### MCP Server
gitstack includes an MCP (Model Context Protocol) server for AI assistants like Claude Code. See [docs/MCP.md](docs/MCP.md) for resources and tools reference.
## Comparison
| Author statistics | ✅ | ❌ | ❌ | ❌ |
| File heatmap | ✅ | ❌ | ❌ | ❌ |
| Code ownership | ✅ | ❌ | ❌ | ❌ |
| Impact score | ✅ | ❌ | ❌ | ❌ |
| **Health dashboard** | ✅ | ❌ | ❌ | ❌ |
| Branch health / recommendations | ✅ | ❌ | ❌ | ❌ |
| Smart filter syntax | ✅ | ❌ | ❌ | ❌ |
| Dashboard layout | ✅ | ❌ | ❌ | ❌ |
| Commit range filter | ✅ | ❌ | ❌ | ❌ |
| Branch graph | ✅ | ✅ | ✅ | ✅ |
| Staging/commit | ✅ | ❌ | ✅ | ✅ |
| Pull/Push | ✅ | ✅ | ✅ | ✅ |
| Branch create/delete | ✅ | ✅ | ✅ | ✅ |
| Interactive rebase | ❌ | ❌ | ✅ | ❌ |
| CLI/JSON output | ✅ | ❌ | ❌ | ❌ |
| MCP server | ✅ | ❌ | ❌ | ❌ |
## Keybindings
### Navigation
| `j` / `k` | Move down / up |
| `g` / `G` | Go to top / bottom |
| `Ctrl+d` / `Ctrl+u` | Page down / up |
### Dashboard
| `1`-`5` | Switch sidebar panel |
| `Tab` | Toggle sidebar/main focus |
| `h` / `l` | Focus sidebar / main panel |
### Views
| `A` | Author statistics |
| `H` | File heatmap |
| `t` | Branch topology |
| `D` | Health dashboard |
| `.` | Quick action menu |
### Actions
| `/` | Open filter |
| `Enter` | Show detail / expand diff |
| `y` | Copy commit hash |
| `b` | Branch select |
| `s` | Status view |
| `?` | Help |
| `q` | Quit |
> Full keybinding reference: [docs/KEYBINDINGS.md](docs/KEYBINDINGS.md)
## Configuration
Config file: `~/.config/gitstack/config.toml`
```toml
[metrics]
quick_action_usage = true # Enable local quick-action usage tracking (default: false)
```
## License
MIT
---
[日本語版](README.ja.md) · [Design Doc](docs/DESIGN.md)