# 機能設計書 38-vim-fugitive連携

## 概要

本ドキュメントは、space-vimにおけるvim-fugitive連携機能の設計仕様を定義する。vim-fugitiveはVimからGitを操作するための統合プラグインであり、コミット、差分表示、blame、push/pull等のGit操作をVim内で完結させることを可能にする。

### 本機能の処理概要

vim-fugitive連携機能は、VimエディタにGitクライアント機能を統合する。Gitのステータス確認、ステージング、コミット、差分表示、ブレーム表示、プッシュ/プルなどの操作を、Vimを離れることなくキーバインドやコマンドで実行できる。space-vimでは`<Leader>g`プレフィックスのキーバインドでGit操作にアクセスできる。

**業務上の目的・背景**：開発ワークフローにおいて、コード編集とバージョン管理は密接に関連している。vim-fugitiveはエディタとGitを統合することで、コンテキストスイッチを最小化し、開発効率を向上させる。特に頻繁なコミットやブレーム確認が必要な場面で効果を発揮する。

**機能の利用シーン**：
- コード変更後のステージング・コミット
- 変更内容の差分確認（:Gdiffsplit）
- 特定行の変更履歴確認（:Git blame）
- リモートへのプッシュ・プル
- コンフリクト解決時のマージ操作

**主要な処理内容**：
1. ステータス表示（:Git）- 変更ファイル一覧とステージング状態を表示
2. 差分表示（:Gdiffsplit）- 現在ファイルの変更差分を分割表示
3. コミット（:Git commit）- コミットメッセージ入力とコミット実行
4. ブレーム（:Git blame）- 各行の最終変更コミット情報を表示
5. ログ表示（:Gclog）- コミット履歴をQuickfixに表示
6. プッシュ/プル（:Git push/pull）- リモートとの同期

**関連システム・外部連携**：
- Git（必須）- Gitコマンドラインツール
- gv.vim - コミットグラフの視覚的表示
- vim-signify - 行ごとの変更状態表示

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | Fugitive（Git操作画面） | 主画面 | Gitステータス、差分、ログなどの表示・操作 |
| 12 | GV（Gitログビューア） | 関連画面 | vim-fugitiveとの連携によるコミット詳細表示 |

## 機能種別

バージョン管理 / 外部コマンド実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| コマンド引数 | String | No | Gitサブコマンドへの引数 | Gitが受け付ける引数 |
| ファイルパス | String | No | 操作対象のファイル（省略時はカレントファイル） | 有効なファイルパス |

### 入力データソース

- Gitリポジトリ（.git）
- カレントバッファのファイル
- ユーザー入力（コミットメッセージ等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Gitステータス | UI | 変更ファイル一覧・ステージング状態 |
| 差分表示 | UI | ファイルの変更差分 |
| ブレーム情報 | UI | 各行のコミット情報 |
| ログ | UI | コミット履歴 |

### 出力先

- Fugitiveバッファ（専用バッファタイプ）
- 分割ウィンドウ（差分表示）
- Quickfixリスト（ログ）

## 処理フロー

### 処理シーケンス

```
1. Gitコマンド実行
   └─ :Git, :Gdiffsplit, :Git blame 等のコマンド呼び出し
2. Gitリポジトリ検出
   └─ カレントディレクトリから.gitを検索
3. Gitコマンド実行
   └─ 対応するgitサブコマンドを実行
4. 結果表示
   └─ 専用バッファまたは分割ウィンドウに結果を表示
5. ユーザー操作
   └─ ステージング、コミット、ナビゲーション等
```

### フローチャート

```mermaid
flowchart TD
    A[Fugitiveコマンド実行] --> B{コマンド種別}
    B -->|:Git| C[ステータス画面表示]
    B -->|:Gdiffsplit| D[差分分割表示]
    B -->|:Git blame| E[ブレーム表示]
    B -->|:Git commit| F[コミット画面表示]
    B -->|:Gclog| G[ログをQuickfixに表示]
    C --> H[ユーザー操作待ち]
    D --> I[差分確認]
    E --> J[コミット情報確認]
    F --> K[コミットメッセージ入力]
    G --> L[コミット選択]
    H --> M{操作種別}
    M -->|s| N[ステージング]
    M -->|u| O[アンステージ]
    M -->|cc| P[コミット]
    M -->|Enter| Q[ファイルを開く]
    K --> R[コミット実行]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 遅延読み込み | speed_up_via_timer有効時、800ms後にfugitiveをロード | 設定有効時 |
| BR-02 | Gitリポジトリ必須 | Gitリポジトリ外では機能が動作しない | 常時 |
| BR-03 | Leader gプレフィックス | Git関連操作は`<Leader>g`で始まるキーバインド | 常時 |
| BR-04 | ブレーム画面のキーバインド | fugitiveblame画面では`q`で終了 | ブレーム表示時 |

### 計算ロジック

該当なし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FUG-001 | リポジトリ外 | Gitリポジトリ外でコマンド実行 | エラーメッセージ表示 |
| FUG-002 | Git未インストール | Gitがシステムにない | Gitのインストールを案内 |
| FUG-003 | コンフリクト | マージコンフリクト発生時 | コンフリクト解決UIを表示 |

### リトライ仕様

特になし。Gitコマンドのエラーはそのまま表示。

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

Gitのトランザクション（コミット）に準じる。

## パフォーマンス要件

- ステータス表示: 1秒以内
- 差分表示: 2秒以内
- ブレーム表示: ファイルサイズに依存

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

- リモート操作（push/pull）は認証情報に注意
- コミット履歴に機密情報が含まれないよう注意

## 備考

- vim-fugitiveはTim Pope氏による定番プラグイン
- :Git（旧:Gstatus）でインタラクティブなステータス画面
- gv.vimとの併用でグラフィカルなログ表示も可能

---

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

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

### 推奨読解順序

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

キーバインドの定義構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | leader.vim | `core/autoload/spacevim/map/leader.vim` | s:leader_map['g']の定義 |

**読解のコツ**: `s:leader_map['g']`がGit関連のキーバインドを定義。'name': '+git/version-control'で始まり、各サブキーでGit操作を定義。

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

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

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

**主要処理フロー**:
1. **1行目**: gv.vimの遅延読み込み（on: ['GV', 'GV!']）
2. **3-7行目**: speed_up_via_timer有効時の遅延読み込み
3. **4行目**: `MP 'tpope/vim-fugitive', { 'on': [] }`
4. **7行目**: `timer_start(800, 'spacevim#defer#fugitive')`

#### Step 3: キーバインド設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+version-control/git/config.vim` | キーマッピングの定義 |

**主要処理フロー**:
- **4行目**: `<Leader>gs :Git<CR>` - ステータス表示
- **5行目**: `<Leader>gd :Gdiffsplit<CR>` - 差分表示
- **6行目**: `<Leader>gc :Git commit<CR>` - コミット
- **7行目**: `<Leader>gb :Git blame<CR>` - ブレーム
- **8行目**: `<Leader>gl :Gclog<CR>` - ログ表示
- **9行目**: `<Leader>gp :Git push<CR>` - プッシュ
- **10-12行目**: read, write, edit操作
- **14行目**: `<Leader>gi :Git add -p %<CR>` - インタラクティブステージング

#### Step 4: ブレーム画面の設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | fugitiveblame.vim | `core/ftplugin/fugitiveblame.vim` | ブレーム画面固有設定 |

**主要処理フロー**:
- **1行目**: `nnoremap <silent><buffer> q :q!<CR>` - qキーで終了

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

```
<Leader>gs (キーバインド)
    │
    └─ :Git
           │
           └─ vim-fugitive
                  │
                  └─ git status
                         │
                         └─ Fugitiveバッファ表示
```

### データフロー図

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

キー入力 ──────▶ config.vim ─────────▶ Fugitiveコマンド
                       │                    │
                       │                    ▼
                       │              vim-fugitive
                       │                    │
                       │                    ▼
                       │               git コマンド
                       │                    │
                       └────────────────────┘
                                │
                                ▼
                         Fugitiveバッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+version-control/git/packages.vim` | 設定 | vim-fugitiveプラグインのロード |
| config.vim | `layers/+version-control/git/config.vim` | 設定 | キーバインド設定 |
| leader.vim | `core/autoload/spacevim/map/leader.vim` | ソース | Leaderキーマップ定義 |
| fugitiveblame.vim | `core/ftplugin/fugitiveblame.vim` | 設定 | ブレーム画面固有設定 |
