# 機能設計書 40-gv.vim連携

## 概要

本ドキュメントは、space-vimにおけるgv.vim連携機能の設計仕様を定義する。gv.vimはGitのコミット履歴をグラフィカルに表示するプラグインであり、vim-fugitiveと連携してブランチ構造やコミット詳細を視覚的に確認できる。

### 本機能の処理概要

gv.vim連携機能は、Gitのコミット履歴をツリービューアで表示し、ブランチ構造やマージポイントを視覚的に把握できるようにする。各コミットの詳細（差分、変更ファイル等）もVim内で確認でき、コードレビューや履歴調査を効率的に行える。

**業務上の目的・背景**：大規模プロジェクトでは、コミット履歴が複雑になりブランチ構造の把握が困難になる。gv.vimはグラフィカルなログ表示により、プロジェクトの変更履歴を直感的に理解できるようにする。また、特定のコミットの詳細を素早く確認できることで、バグ調査やコードレビューを効率化する。

**機能の利用シーン**：
- プロジェクトのコミット履歴を視覚的に確認したい場合
- 特定のファイルの変更履歴を追跡したい場合
- ブランチのマージポイントを確認したい場合
- 過去のコミットの詳細（差分）を確認したい場合
- 特定のコミット範囲のログを表示したい場合

**主要な処理内容**：
1. コミットグラフ表示（:GV）- 全コミット履歴をグラフ表示
2. カレントファイルログ（:GV!）- 現在ファイルに関連するコミットのみ表示
3. コミット詳細表示 - 選択コミットの差分・変更ファイルを表示
4. ビジュアル選択でのログ表示 - 選択範囲に関連するコミットを表示

**関連システム・外部連携**：
- vim-fugitive（必須）- Gitコマンドの実行基盤
- Git - コミット履歴の取得

**権限による制御**：特になし。Git操作はユーザーの権限に依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | GV（Gitログビューア） | 主画面 | Gitコミット履歴のグラフィカル表示 |

## 機能種別

UI表示 / バージョン管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| コミット範囲 | String | No | 表示するコミット範囲（例: HEAD~10..HEAD） | 有効なGitリビジョン指定 |
| ファイルパス | String | No | 特定ファイルのログを表示（:GV!時） | 有効なファイルパス |

### 入力データソース

- Gitコミット履歴（git log）
- vim-fugitiveのGit統合機能

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| コミットグラフ | UI | ブランチ構造を示すASCIIアート |
| コミット情報 | UI | ハッシュ、著者、日付、メッセージ |
| コミット詳細 | UI | 選択コミットの差分・変更ファイル |

### 出力先

- GVバッファ（専用バッファタイプ）
- プレビューウィンドウ（コミット詳細）

## 処理フロー

### 処理シーケンス

```
1. GVコマンド実行
   └─ :GV または :GV! コマンド呼び出し
2. Gitログ取得
   └─ git log --graph 等のコマンドを実行
3. グラフ構築
   └─ コミットグラフをASCIIアートで構築
4. バッファ表示
   └─ GVバッファにコミットログを表示
5. ユーザー操作
   └─ コミット選択、詳細表示、ナビゲーション
```

### フローチャート

```mermaid
flowchart TD
    A[GVコマンド実行] --> B{コマンド種別}
    B -->|:GV| C[全コミットログ取得]
    B -->|:GV!| D[カレントファイルログ取得]
    B -->|ビジュアル選択+:GV| E[選択範囲のログ取得]
    C --> F[git log --graph実行]
    D --> F
    E --> F
    F --> G[コミットグラフ構築]
    G --> H[GVバッファ表示]
    H --> I[ユーザー操作待ち]
    I --> J{操作種別}
    J -->|Enter| K[コミット詳細表示]
    J -->|o| L[新規タブで詳細表示]
    J -->|O| M[新規ウィンドウで詳細表示]
    J -->|q| N[GV終了]
    K --> I
    L --> I
    M --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 遅延読み込み | :GV または :GV! コマンド実行時にロード | 常時 |
| BR-02 | fugitive依存 | vim-fugitiveが読み込まれている必要がある | 常時 |
| BR-03 | Gitリポジトリ必須 | Gitリポジトリ外では機能しない | 常時 |
| BR-04 | Enter選択 | Enterキーでコミット詳細を表示 | GVバッファ内 |

### 計算ロジック

該当なし

## データベース操作仕様

該当なし（Gitリポジトリへの操作）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| GV-001 | リポジトリ外 | Gitリポジトリ外でコマンド実行 | エラーメッセージ表示 |
| GV-002 | fugitive未読み込み | vim-fugitiveがロードされていない | プラグインの読み込みを確認 |

### リトライ仕様

特になし。エラー時はメッセージを表示し、処理を中断。

## トランザクション仕様

該当なし（読み取り専用操作）

## パフォーマンス要件

- コミットログ表示: 2秒以内（1000コミットまで）
- コミット詳細表示: 1秒以内
- 大規模リポジトリでは表示に時間がかかる可能性あり

## セキュリティ考慮事項

- コミット履歴に機密情報が含まれる可能性に注意
- Git操作はユーザーの権限で実行

## 備考

- junegunn氏（fzf作者）によるプラグイン
- vim-fugitiveとの連携が前提
- グラフ表示には等幅フォントを推奨

---

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

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

### 推奨読解順序

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

gv.vimのコマンド構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+version-control/git/packages.vim` | gv.vimのロード設定 |

**読解のコツ**: gv.vimは`:GV`と`:GV!`の2つのコマンドで遅延読み込みされる。`:GV`は全コミット、`:GV!`はカレントファイルのコミットを表示。

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

gv.vimのプラグインロードを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+version-control/git/packages.vim` | プラグインロード |

**主要処理フロー**:
1. **1行目**: `MP 'junegunn/gv.vim', { 'on': ['GV', 'GV!'] }` - 遅延読み込み設定

#### Step 3: 関連設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | leader.vim | `core/autoload/spacevim/map/leader.vim` | 関連キーマップ（あれば） |

**主要処理フロー**:
- gv.vim固有のキーバインドはspace-vimでは定義されていない
- `:GV`コマンドを直接実行して使用

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

```
:GV (コマンド)
    │
    └─ gv.vim
           │
           ├─ vim-fugitive
           │      └─ Git統合基盤
           │
           └─ git log --graph
                  │
                  └─ コミットグラフ生成
                         │
                         └─ GVバッファ表示
```

### データフロー図

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

:GV/:GV! ──────▶ gv.vim ─────────────▶ vim-fugitive
                       │                    │
                       │                    ▼
                       │              git log --graph
                       │                    │
                       │                    ▼
                       │              コミットグラフ構築
                       │                    │
                       └────────────────────┘
                                │
                                ▼
                         GVバッファ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+version-control/git/packages.vim` | 設定 | gv.vimプラグインのロード |
