gitstack 2.21.0

# gitstack

[![Crates.io](https://img.shields.io/crates/v/gitstack.svg)](https://crates.io/crates/gitstack)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> **Git history viewer focused on analysis and insights**

<!-- ![hero](assets/hero.gif) -->

## 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?"*

## Install

```bash
cargo install gitstack
```

Or build from source:
```bash
git clone https://github.com/Hiro-Chiba/gitstack
cd gitstack
cargo install --path .
```

## Features

### Analysis Suite

<!-- ![analysis](assets/analysis.gif) -->

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 stale branch detection |

### Smart Filter

<!-- ![filter](assets/filter.gif) -->

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`

### 2-Pane Layout

<!-- ![2pane](assets/2pane.gif) -->

Toggle with `v` to see commit details alongside the graph:

```
┌─ Graph ─────────────────┬─ Details ────────────────────┐
│ ● abc123 feat: auth     │ Author: John Doe             │
│ │                       │ Date: 2024-01-15 10:30       │
│ ○ def456 fix: bug       │                              │
│ │                       │ feat: add authentication     │
│ ◆ ghi789 Merge          │                              │
│ │                       │ - Add login endpoint         │
│ ○ jkl012 init           │ - Add JWT validation         │
└─────────────────────────┴──────────────────────────────┘
```

### 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

### CLI Mode (Non-Interactive)

For AI coding assistants (Claude Code, etc.) and scripting, gitstack provides JSON output:

```bash
gitstack --stats       # Author statistics
gitstack --heatmap     # File change frequency
gitstack --impact      # Commit impact scores
gitstack --coupling    # File change coupling
gitstack --log -n 5    # Recent commits
```

Example output (`--stats`):
```json
{
  "generated_at": "2026-02-03T10:30:00+0900",
  "total_commits": 150,
  "author_count": 3,
  "authors": [
    {"name": "Alice", "commit_count": 80, "insertions": 5000, ...}
  ]
}
```

| Option | Description |
|--------|-------------|
| `--stats` | Author statistics as JSON |
| `--heatmap` | File heatmap as JSON |
| `--impact` | Impact scores as JSON |
| `--coupling` | Change coupling as JSON |
| `--log -n N` | Latest N commits as JSON (default: 10, max: 10000) |
| `--help` | Show help |
| `--version` | Show version |

## Comparison

| Feature | gitstack | keifu | lazygit | tig |
|---------|:--------:|:-----:|:-------:|:---:|
| Author statistics | ✅ | ❌ | ❌ | ❌ |
| File heatmap | ✅ | ❌ | ❌ | ❌ |
| Code ownership | ✅ | ❌ | ❌ | ❌ |
| Impact score | ✅ | ❌ | ❌ | ❌ |
| Branch health / topology | ✅ | ❌ | ❌ | ❌ |
| Smart filter syntax | ✅ | ❌ | ❌ | ❌ |
| 2-pane layout | ✅ | ❌ | ✅ | ❌ |
| Commit range filter | ✅ | ❌ | ❌ | ❌ |
| Branch graph | ✅ | ✅ | ✅ | ✅ |
| Staging/commit | ✅ | ❌ | ✅ | ✅ |
| Pull/Push | ✅ | ✅ | ✅ | ✅ |
| Branch create/delete | ✅ | ✅ | ✅ | ✅ |
| Interactive rebase | ❌ | ❌ | ✅ | ❌ |
| CLI/JSON output | ✅ | ❌ | ❌ | ❌ |

## Keybindings

### Navigation
| Key | Action |
|-----|--------|
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `g` | Go to top |
| `G` | Go to bottom |
| `Ctrl+d` | Page down |
| `Ctrl+u` | Page up |

### Views
| Key | Action |
|-----|--------|
| `Enter` | Show commit details / diff |
| `P` | Show file patch (in detail view) |
| `v` | Toggle 2-pane layout |
| `A` | Author statistics |
| `H` | File heatmap |
| `T` | Commit timeline |
| `O` | Code ownership |
| `I` | Impact scores |
| `t` | Branch topology |

### Actions
| Key | Action |
|-----|--------|
| `/` | Open filter |
| `Esc` | Clear filter / close view |
| `y` | Copy commit hash |
| `b` | Show blame view |
| `s` | Open status view |
| `F` | Fetch from remote |
| `?` | Show help |
| `q` | Quit |

### Status View (s)
| Key | Action |
|-----|--------|
| `Space` | Stage/unstage file |
| `a` | Stage all |
| `A` | Unstage all |
| `c` | Commit |
| `l` | Pull from remote |
| `p` | Push to remote |

### Branch Select (b)
| Key | Action |
|-----|--------|
| `Enter` | Checkout branch |
| `n` | Create new branch |
| `d` | Delete branch |

## Configuration

Config file: `~/.config/gitstack/config.toml`

```toml
[display]
date_format = "relative"  # or "absolute"
show_stats = true

[keybindings]
quit = "q"
help = "?"
```

## License

MIT

---

[日本語版](README.ja.md) · [Design Doc](docs/DESIGN.md)