gitstack 3.0.12

# 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履歴ビューア**
>
> *AI支援開発時代に最適化 - Claude Codeなどとの併用に対応*

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

## なぜ gitstack？

| ツール | フォーカス | 最適な用途 |
|--------|-----------|-----------|
| lazygit | Git操作 | ステージング、リベース、チェリーピック |
| tig | ログ閲覧 | コミットの素早い確認 |
| keifu | グラフ可視化 | 美しいブランチ表示 |
| **gitstack** | **分析 & インサイト** | **コードベースの理解** |

gitstackはこんな疑問に答えます：
- *「このモジュールは誰が作業してきた？」*
- *「どのファイルが頻繁に変更されている？」*
- *「放置されているブランチはある？」*
- *「このプロジェクトは健全？」*

## インストール

```bash
cargo install gitstack
```

ソースからビルド：
```bash
git clone https://github.com/Hiro-Chiba/gitstack
cd gitstack
cargo install --path .
```

## 機能

### 分析スイート

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

キー1つで即座にインサイトを取得：

| キー | ビュー | 表示内容 |
|------|--------|----------|
| `A` | 著者統計 | 著者ごとのコミット数、追加/削除行数 |
| `H` | ヒートマップ | 最も頻繁に変更されるファイル |
| `T` | タイムライン | 時間帯/曜日別のコミット活動 |
| `O` | オーナーシップ | ファイル/ディレクトリごとのコード所有者 |
| `I` | Impact Score | コミット影響度スコア（0.0-1.0） |
| `t` | トポロジー | ブランチ健全性と推奨アクション |
| `D` | ヘルスダッシュボード | プロジェクト健全性スコア（0-100） |

### スマートフィルター

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

直感的な構文による強力なフィルタリング：

```
/author:john              # 著者でフィルター
/since:7days              # 最近のコミット
/until:2024-01-01         # 指定日以前
/message:fix              # コミットメッセージ検索
/file:src/main.rs         # 特定ファイルに関するコミット
/hash:abc123..def456      # コミット範囲
```

フィルターの組み合わせ： `/author:john since:1week file:*.rs`

### アダプティブレイアウト (v3.0+)

`v`でビューモードを切り替え：

| モード | 幅 | 最適な用途 |
|--------|-----|-----------|
| Normal | 80列以上 | フル機能のグラフ表示 |
| Focus | 30-39列 | 重要信号付きの狭幅表示 |
| Compact | 40-79列 | 詳細付き2ペインレイアウト |
| UltraCompact | 20-29列 | Claude Code分割ペイン向け最小表示 |

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

Compactモードではグラフと詳細を並べて表示：

```
┌─ グラフ ────────────────┬─ 詳細 ─────────────────────────┐
│ ● abc123 feat: 認証追加 │ Author: John Doe               │
│ │                       │ Date: 2024-01-15 10:30         │
│ ○ def456 fix: バグ修正  │                                │
│ │                       │ feat: 認証機能を追加           │
│ ◆ ghi789 Merge          │                                │
│ │                       │ - ログインエンドポイント追加   │
│ ○ jkl012 init           │ - JWT検証を追加                │
└─────────────────────────┴────────────────────────────────┘
```

### ブランチグラフ

スマートな色割り当てによるカラーコード付きブランチ可視化：
- 隣接レーンは同じ色にならない
- 同じ分岐元からのブランチは異なる色を取得
- 適切な線接続によるクリアなマージ可視化

### プロジェクトヘルスダッシュボード (v3.0+)

`D`を押してプロジェクト健全性を表示：

```
┌─ ヘルスダッシュボード ─────────────────────────────┐
│  総合スコア: 78 / 100 (Good)                       │
│  ████████░░                                        │
│                                                    │
│  品質         ████████░░  82%                      │
│  テスト健全性 ██████░░░░  65%                      │
│  バスファクター █████████░  90%                    │
│  技術的負債   ███████░░░  75%                      │
│                                                    │
│  ⚠ Warning: 放置ブランチが3件あります              │
│  ℹ Info: テストカバレッジを改善できます            │
└────────────────────────────────────────────────────┘
```

### ブランチ推奨 (v3.0+)

トポロジービュー（`t`）で各ブランチの推奨アクションを表示：

| アイコン | アクション | 意味 |
|---------|----------|------|
| 🗑 | Delete | マージ済み or 60日以上放置 |
| ↻ | Rebase | mainから大幅に遅れている |
| ⤵ | Merge | マージ可能（ahead > 0） |
| 👁 | Review | 長寿命ブランチ、要確認 |

### CLIモード（非対話）

AIコーディングアシスタント（Claude Codeなど）やスクリプトから利用可能なJSON出力：

```bash
gitstack --stats       # 著者統計
gitstack --heatmap     # ファイル変更頻度
gitstack --impact      # コミット影響度スコア
gitstack --coupling    # ファイル変更結合度
gitstack --health      # プロジェクト健全性スコア
gitstack --summary     # 現在の要約コンテキスト
gitstack --pack        # AI向けインサイトパック
gitstack --review-pack # AIレビュー判断パック
gitstack --next-actions # 優先アクション一覧
gitstack --verify      # パッチのリスク判定
gitstack --why act-add-tests # 推奨理由の説明
gitstack --handoff --target codex # AIハンドオフ文脈
gitstack --log -n 5    # 最新コミット
```

出力例（`--stats`）：
```json
{
  "generated_at": "2026-02-03T10:30:00+0900",
  "total_commits": 150,
  "author_count": 3,
  "authors": [
    {"name": "Alice", "commit_count": 80, "insertions": 5000, ...}
  ]
}
```

| オプション | 説明 |
|-----------|------|
| `--stats` | 著者統計をJSON出力 |
| `--heatmap` | ファイルヒートマップをJSON出力 |
| `--impact` | 影響度スコアをJSON出力 |
| `--coupling` | 変更結合度をJSON出力 |
| `--health` | プロジェクト健全性スコアをJSON出力 |
| `--summary` | 現在の要約コンテキストをJSON/Markdown出力 |
| `--pack` | AI向けインサイトパックをJSON/Markdown出力 |
| `--review-pack` | AIレビュー判断パックをJSON/Markdown出力 |
| `--next-actions` | 優先アクション一覧をJSON/Markdown出力 |
| `--verify` | パッチリスク判定をJSON/Markdown出力 |
| `--why ID` | 推奨アクションIDの根拠説明 |
| `--handoff --target ...` | Claude/Codex/Copilot向けハンドオフ文脈 |
| `--log -n N` | 最新N件のコミットをJSON出力（デフォルト: 10、最大: 10000） |
| `--clear-cache` | 分析キャッシュを削除 |
| `--help` | ヘルプ表示 |
| `--version` | バージョン表示 |

### MCPサーバー (v3.0+)

gitstackはClaude CodeなどのAIアシスタント向けMCP（Model Context Protocol）サーバーを同梱しています。

```bash
# MCPサーバーをビルド
cargo build -p gitstack-mcp --release

# Claude CodeのMCP設定に追加
```

**利用可能なリソース:**

| URI | 説明 |
|-----|------|
| `gitstack://stats/authors` | 著者統計 |
| `gitstack://stats/heatmap` | ファイル変更頻度 |
| `gitstack://stats/ownership` | コードオーナーシップ |
| `gitstack://stats/quality` | コミット品質スコア |
| `gitstack://stats/impact` | コミット影響度スコア |
| `gitstack://stats/coupling` | 変更結合度 |
| `gitstack://stats/bus-factor` | バスファクター分析 |
| `gitstack://stats/tech-debt` | 技術的負債 |
| `gitstack://health/dashboard` | プロジェクト健全性スコア |
| `gitstack://branch/recommendations` | ブランチ推奨アクション |
| `gitstack://summary/now` | 現在の要約コンテキスト |
| `gitstack://insight/pack` | AI向けインサイトパック |
| `gitstack://signals/risk` | コミットリスク信号 |
| `gitstack://review/pack` | AIレビュー判断パック |
| `gitstack://review/actions` | 優先アクション一覧 |
| `gitstack://review/why/<id>` | 推奨理由の説明 |
| `gitstack://handoff/context` | AIハンドオフ文脈 |

**利用可能なツール:**

| ツール | 説明 |
|--------|------|
| `get_file_history` | ファイルのコミット履歴 |
| `get_author_commits` | 著者別コミット |
| `get_file_owners` | ファイル/ディレクトリの所有者 |
| `get_hot_files` | 最も変更されているファイル |
| `get_project_health` | プロジェクト健全性スコア |
| `get_coupled_files` | 一緒に変更されるファイル |
| `get_branch_recommendations` | ブランチ推奨アクション |
| `get_context_pack` | AI向けコンテキストパックを取得 |
| `get_risk_summary` | 現在のリスク要約を取得 |
| `get_review_pack` | AIレビュー判断パックを取得 |
| `get_next_actions` | 優先アクション一覧を取得 |
| `verify_patch_risk` | 現在パッチのリスク判定を取得 |
| `explain_recommendation` | 推奨アクションの理由を取得 |

## 比較

| 機能 | gitstack | keifu | lazygit | tig |
|------|:--------:|:-----:|:-------:|:---:|
| 著者統計 | ✅ | ❌ | ❌ | ❌ |
| ファイルヒートマップ | ✅ | ❌ | ❌ | ❌ |
| コードオーナーシップ | ✅ | ❌ | ❌ | ❌ |
| Impact Score | ✅ | ❌ | ❌ | ❌ |
| **ヘルスダッシュボード** | ✅ | ❌ | ❌ | ❌ |
| ブランチ健全性/推奨 | ✅ | ❌ | ❌ | ❌ |
| スマートフィルター構文 | ✅ | ❌ | ❌ | ❌ |
| アダプティブレイアウト (20列以上) | ✅ | ❌ | ❌ | ❌ |
| コミット範囲フィルター | ✅ | ❌ | ❌ | ❌ |
| ブランチグラフ | ✅ | ✅ | ✅ | ✅ |
| ステージング/コミット | ✅ | ❌ | ✅ | ✅ |
| Pull/Push | ✅ | ✅ | ✅ | ✅ |
| ブランチ作成/削除 | ✅ | ✅ | ✅ | ✅ |
| インタラクティブリベース | ❌ | ❌ | ✅ | ❌ |
| CLI/JSON出力 | ✅ | ❌ | ❌ | ❌ |
| MCPサーバー | ✅ | ❌ | ❌ | ❌ |

## キーバインド

### ナビゲーション
| キー | 操作 |
|------|------|
| `j` / `↓` | 下へ移動 |
| `k` / `↑` | 上へ移動 |
| `g` | 先頭へ |
| `G` | 末尾へ |
| `Ctrl+d` | ページダウン |
| `Ctrl+u` | ページアップ |

### ビュー
| キー | 操作 |
|------|------|
| `Enter` | コミット詳細/diff表示 |
| `P` | ファイルパッチ表示（詳細ビュー内） |
| `v` | ビューモード切替 (Normal → Compact → Focus → UltraCompact) |
| `S` | ヘッダー要約行を表示/非表示 |
| `A` | 著者統計 |
| `H` | ファイルヒートマップ |
| `T` | コミットタイムライン |
| `O` | コードオーナーシップ |
| `I` | Impact Score |
| `t` | ブランチトポロジー（推奨アクション付き） |
| `D` | プロジェクトヘルスダッシュボード |

### アクション
| キー | 操作 |
|------|------|
| `/` | フィルターを開く |
| `Esc` | フィルターをクリア/ビューを閉じる |
| `y` | コミットハッシュをコピー |
| `Y` | Insight Packをstdout出力 |
| `b` | Blameビューを表示 |
| `s` | ステータスビューを開く |
| `F` | リモートからフェッチ |
| `?` | ヘルプを表示 |
| `q` | 終了 |

### ステータスビュー (s)
| キー | 操作 |
|------|------|
| `Space` | ファイルをステージ/アンステージ |
| `a` | すべてステージ |
| `A` | すべてアンステージ |
| `c` | コミット |
| `l` | リモートからプル |
| `p` | リモートへプッシュ |

### ブランチ選択 (b)
| キー | 操作 |
|------|------|
| `Enter` | ブランチをチェックアウト |
| `n` | 新しいブランチを作成 |
| `d` | ブランチを削除 |

## 設定

設定ファイル： `~/.config/gitstack/config.toml`

```toml
[display]
date_format = "relative"  # または "absolute"
show_stats = true

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

## ライセンス

MIT

---

[English](README.md) · [設計書](docs/DESIGN.md)