Readme
gitstack
Git history viewer focused on analysis and insights
Your codebase review companion in the AI-assisted development era
Why gitstack?
Tool
Focus
Best For
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?"
Prerequisites
Install
cargo install gitstack
Or build from source:
git clone https://github.com/Hiro-Chiba/gitstack
cd gitstack
cargo install -- path .
Quick Start
Install : cargo install gitstack
Launch : gitstack (run in any git repository)
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:
Key
View
What it shows
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:
Icon
Action
Meaning
🗑
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:
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
AI-Aware Review & Analysis
gitstack provides features for understanding and reviewing AI-generated changes:
Change Intent Icons : Auto-classified commit intent (✦Feature/✧Fix/↻Refactor/◇Docs/◈Test/○Chore)
AI Session Visualization : Detects AI sessions from co-author patterns and displays session separators
Staged Risk Scoring : Risk badge in Files panel based on file count, heatmap, ownership, and change size
Watch Mode (W ): Real-time file change detection (500ms interval)
Review Queue (R ): Manage MCP review requests with approve/reject workflow
PR Split Suggestions : Auto-detect independent clusters when 10+ files are staged
Convenience Operations
These supplementary operations let you stay in the flow without switching tools:
Smart Staging (S in status): Intelligent staging group suggestions by directory and test/implementation pairs
One-key PR Creation (P ): Create PRs with auto-generated body via gh CLI
MCP Write Tools : 8 Git write operations with dry_run safety (default: true)
Background Operations
gitstack moves all heavy Git operations off the main thread to eliminate UI freezes in large repositories:
Diff Calculation : Commit diff loading runs in a background thread
Pull/Push : Network operations no longer block the UI
Event Reload : Post-checkout/commit/fetch event reloading is fully async
Quick Action Analysis : Timeline, Ownership, Impact Score, Change Coupling, Quality Score calculations run in background threads
Blame : File blame loading runs asynchronously with a "Loading..." indicator
MCP Server
gitstack includes an MCP (Model Context Protocol) server for AI assistants like Claude Code. See docs/MCP.md for resources and tools reference.
Comparison
Feature
gitstack
keifu
lazygit
tig
Author statistics
✅
❌
❌
❌
File heatmap
✅
❌
❌
❌
Code ownership
✅
❌
❌
❌
Impact score
✅
❌
❌
❌
Health dashboard
✅
❌
❌
❌
AI session tracking
✅
❌
❌
❌
Change intent icons
✅
❌
❌
❌
Staged risk scoring
✅
❌
❌
❌
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
Key
Action
j / k
Move down / up
g / G
Go to top / bottom
Ctrl+ d / Ctrl+ u
Page down / up
Dashboard
Key
Action
1 -5
Switch sidebar panel
Tab
Toggle sidebar/main focus
h / l
Focus sidebar / main panel
Views
Key
Action
.
Quick action menu (Author Stats, Heatmap, etc.)
t
Branch topology
D
Health dashboard
Actions
Key
Action
/
Open filter
Enter
Show detail / expand diff
y
Copy commit hash
b
Branch select
s
Status view
W
Watch mode
P
Create PR
R
Review queue
?
Help
q
Quit
Full keybinding reference: docs/KEYBINDINGS.md
Configuration
Config file: ~/.config/gitstack/config.toml
[ metrics ]
quick_action_usage = true # Enable local quick-action usage tracking (default: false)
License
MIT
日本語版 · Design Doc