# 画面設計書 20-VC Gutter

## 概要

本ドキュメントは、Doom EmacsにおけるVC Gutter（バージョン管理ガター）画面の設計仕様を定義するものである。diff-hlパッケージを利用したGit差分の行番号横表示について、その表示仕様、操作方法、およびmagit連携を記載する。

### 本画面の処理概要

VC Gutter画面は、Gitの変更状態（追加、変更、削除）を行番号横のガター領域に色分け表示し、差分を視覚的に把握できるようにする機能である。

**業務上の目的・背景**：バージョン管理下のファイルを編集する際、どの行が変更されたかを常に把握することは重要である。本機能は、ファイルの変更状態をリアルタイムでガター領域に表示することで、コミット前のレビューや、変更箇所の特定を容易にする。VSCodeやその他のモダンなエディタで標準的なガター表示をEmacsに提供する。

**画面へのアクセス方法**：Doom Emacs起動後、ファイルを開くと自動的に`diff-hl-mode`が有効化される（`doom-first-file`フックによりglobal-diff-hl-modeが有効化）。

**主要な操作・処理内容**：
1. 追加行の緑色マーカー表示
2. 変更行の青/黄色マーカー表示
3. 削除行の赤色マーカー表示
4. ハンク（変更塊）間のナビゲーション
5. ハンクの部分的ステージング
6. ハンクの取り消し（リバート）

**画面遷移**：VC Gutterは編集バッファのガター領域に表示される。ハンクを選択するとdiffポップアップが表示される。

**権限による表示制御**：本機能に権限による表示制御はない。全ユーザーが同一の機能を利用可能である。Gitリポジトリ外のファイルでは表示されない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 39 | バージョン管理状態をガターに表示 | 主機能 | Git差分行の色分け表示 |
| 54 | バージョン管理統合 | 補助機能 | vc連携による変更状態取得 |

## 画面種別

オーバーレイ（編集画面への視覚的補助）

## URL/ルーティング

Emacsモード: `diff-hl-mode`, `diff-hl-flydiff-mode`
表示位置: バッファ左側のフリンジ領域

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| Gitリポジトリ | 入力 | ディレクトリ | ファイルが属するGitリポジトリ |
| HEAD参照 | 入力 | コミット | 比較対象のコミット |
| 差分情報 | 出力 | リスト | 変更、追加、削除行の情報 |
| ガターマーカー | 出力 | ビットマップ | 変更タイプを示す色付きマーカー |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|---------|------|
| 追加マーカー | 左フリンジ | 新規追加行を示す緑色バー |
| 変更マーカー | 左フリンジ | 変更行を示す青色バー |
| 削除マーカー | 左フリンジ | 削除行を示す赤色三角 |

## イベント仕様

### 1-自動モード有効化

`doom-first-file`フックで`global-diff-hl-mode`が有効化され、バージョン管理下のファイルで自動的にガターが表示される。

### 2-リアルタイム更新（flydiff）

`diff-hl-flydiff-mode`が有効な場合、保存を待たずにリアルタイムで差分が更新される（macOS以外でデフォルト有効、遅延0.5秒）。

### 3-次のハンクへ移動

`diff-hl-next-hunk`（Evilモードでは`]`キー）で次の変更塊に移動。

### 4-前のハンクへ移動

`diff-hl-previous-hunk`（Evilモードでは`[`キー）で前の変更塊に移動。

### 5-ハンクのステージング

`diff-hl-show-hunk-stage-hunk`（Evilモードでは`S`キー）で現在のハンクをGitステージに追加。

### 6-ハンクのリバート

`diff-hl-revert-hunk`（Evilモードでは`r`キー）で現在のハンクを元に戻す。リバート前にdiffポップアップで確認。

### 7-元テキストのコピー

`diff-hl-show-hunk-copy-original-text`（Evilモードでは`c`キー）で変更前のテキストをコピー。

### 8-ESCキーでの更新

`doom-escape-hook`でESCキー押下時に`+vc-gutter-update-h`が実行され、デバウンス付きで差分が更新される。

### 9-magit連携更新

`magit-post-refresh-hook`でmagit操作後に差分表示が自動更新される。

### 10-Evil insertモード終了時更新

`evil-insert-state-exit-hook`でinsertモード終了時に即座に差分が更新される。

## データベース更新仕様

本機能はGitリポジトリからデータを取得するが、データベースを直接更新しない。

| 操作 | 対象 | 説明 |
|-----|------|------|
| ステージング | Git index | diff-hl-show-hunk-stage-hunkでステージに追加 |
| リバート | 作業ツリー | diff-hl-revert-hunkで変更を破棄 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| なし | - | VC Gutterは基本的にメッセージを表示しない |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| Gitリポジトリ外 | モードを有効化しない |
| リモートファイル | diff-hl-disable-on-remote設定に従う |
| image-mode | diff-hl-global-modesで除外 |
| pdf-view-mode | diff-hl-global-modesで除外 |
| macOS | flydiffモードをデフォルト無効（プロセス管理問題） |
| TRAMPファイル | 一時ファイル警告を抑制 |

## 備考

- diff-hlパッケージを使用
- +prettyフラグで細いバー表示（フリンジの半分幅）
- Git diffアルゴリズムは`--histogram`を使用（高速）
- 非同期更新対応（Emacs 30以降またはスレッド使用）
- ステージ済み変更は表示しない（`diff-hl-show-staged-changes nil`）
- flydiffの遅延は0.5秒（デフォルト0.3秒より若干長め）
- flycheck有効時は右フリンジに配置してdiff-hlとの重複を回避

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

VC Gutterの表示スタイル設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/vc-gutter/config.el` | 6-59行目: +prettyフラグ設定 |

**読解のコツ**: `+vc-gutter-`プレフィックスの変数/関数がDoom独自設定、`diff-hl-`プレフィックスがdiff-hlパッケージ設定。

#### Step 2: エントリーポイントを理解する

diff-hlパッケージの基本設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/vc-gutter/config.el` | 65-68行目: diff-hlパッケージ設定 |

**主要処理フロー**:
1. **66行目**: `doom-first-file`フックで`global-diff-hl-mode`有効化
2. **67行目**: `vc-dir-mode`フックで`turn-on-diff-hl-mode`
3. **68行目**: コマンド宣言（hunk操作）

#### Step 3: flydiffモードを理解する

リアルタイム更新機能を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/vc-gutter/config.el` | 80-85行目: flydiffモード設定 |

**主要処理フロー**:
- **80行目**: macOS以外でflydiffモードを有効化
- **94行目**: 更新遅延を0.5秒に設定

#### Step 4: パフォーマンス設定を理解する

高速化のための設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/ui/vc-gutter/config.el` | 90-98行目: パフォーマンス設定 |

**主要処理フロー**:
- **92行目**: `--histogram`アルゴリズムで高速diff
- **94行目**: 更新遅延0.5秒
- **96行目**: 非同期更新（Emacs 30以降 or スレッド）
- **98行目**: ステージ済み変更は非表示

#### Step 5: Evilキーバインドを理解する

ハンク操作のキーバインドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/ui/vc-gutter/config.el` | 111-122行目: Evilキーマップ |

**主要処理フロー**:
- **114-115行目**: `p`/`n`で前後のハンクに移動
- **116行目**: `c`で元テキストコピー
- **117行目**: `r`でリバート
- **118-121行目**: `[`/`]`/`{`/`}`でナビゲーション
- **122行目**: `S`でステージング

#### Step 6: 更新トリガーを理解する

差分更新のタイミングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | config.el | `modules/ui/vc-gutter/config.el` | 125-140行目: 更新フック |

**主要処理フロー**:
- **126行目**: ESCキー、ウィンドウ切り替え、フレームフォーカスで更新
- **143行目**: magit操作後に更新
- **158-163行目**: Evilのinsertモード終了時に更新

### プログラム呼び出し階層図

```
doom-first-file
    │
    └─ global-diff-hl-mode
           │
           ├─ diff-hl-mode (各バッファ)
           │      │
           │      └─ diff-hl-flydiff-mode (macOS以外)
           │             └─ 遅延0.5秒で自動更新
           │
           └─ dired-mode-hook
                  └─ +vc-gutter-enable-maybe-h

doom-escape-hook / doom-switch-*-hook
    └─ +vc-gutter-update-h
           └─ diff-hl-update (デバウンス付き)

magit-post-refresh-hook
    └─ diff-hl-magit-post-refresh

evil-insert-state-exit-hook
    └─ diff-hl-flydiff-update

diff-hl-show-hunk-map (Evil)
    ├─ p → diff-hl-show-hunk-previous
    ├─ n → diff-hl-show-hunk-next
    ├─ c → diff-hl-show-hunk-copy-original-text
    ├─ r → diff-hl-show-hunk-revert-hunk
    └─ S → diff-hl-show-hunk-stage-hunk
```

### データフロー図

```
[入力]                   [処理]                      [出力]

Gitリポジトリ       ───▶ git diff --histogram  ───▶ 差分情報
                              │
バッファ変更        ───▶      │
                              ▼
                         diff-hl-update         ───▶ ガターマーカー
                              │
                              ├─ 追加行        ───▶ 緑色バー
                              ├─ 変更行        ───▶ 青色バー
                              └─ 削除行        ───▶ 赤色三角

ハンク操作          ───▶ diff-hl-*-hunk       ───▶ Git操作
(ステージ/リバート)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/vc-gutter/config.el` | ソース | メイン設定ファイル、diff-hl設定 |
| packages.el | `modules/ui/vc-gutter/packages.el` | 設定 | パッケージ依存関係定義 |
