# 機能設計書 54-バージョン管理統合

## 概要

本ドキュメントは、Doom Emacsの`emacs/vc`モジュールが提供するバージョン管理統合機能の設計仕様を記述する。Emacs組み込みのvc(Version Control)機能を拡張し、Git、Mercurial、SVNなどのVCSとのシームレスな統合、コンフリクト解決支援、リモートリポジトリへのブラウジング機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：現代のソフトウェア開発において、バージョン管理システムは不可欠なツールである。Emacs内でバージョン管理操作を完結させることで、エディタとターミナル間の切り替えを減らし、開発効率を向上させる。特に、マージコンフリクトの解決やファイル履歴の確認といった頻繁に行う操作を、Emacs内で直感的に行えるようにする。

**機能の利用シーン**：
- ファイルのGit履歴確認（git-timemachine）
- マージコンフリクトの解決（smerge-mode）
- GitHubやGitLabでのファイル/行の共有（browse-at-remote）
- VC注釈（blame）の表示
- バグリファレンスのリンク化

**主要な処理内容**：
1. vc-handled-backendsの最適化（Git, Hg, SVNに限定）
2. smerge-modeによるコンフリクト解決支援
3. git-timemachineによるファイル履歴閲覧
4. browse-at-remoteによるリモートURL生成
5. bug-reference-modeのVC統合（Emacs 27用バックポート）

**関連システム・外部連携**：
- vc.el（Emacs組み込みVC）
- smerge-mode（コンフリクト解決）
- git-timemachine（Git履歴閲覧）
- browse-at-remote（リモートURL）
- git-modes（Gitファイルのシンタックスハイライト）

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | VC Gutter | 関連機能 | Git差分行の色分け表示 |
| - | git-timemachine | 主画面 | ファイル履歴の閲覧・ナビゲーション |
| - | vc-annotate | 主画面 | blame情報の表示 |
| - | smerge-mode | 主画面 | コンフリクト解決操作 |

## 機能種別

バージョン管理統合 / 外部ツール連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| arg | prefix | No | browse-at-remoteでシンボリック/コミットハッシュを切り替え | C-u プレフィックス |

### 入力データソース

- 現在のバッファのファイルパス
- Git/Hg/SVNリポジトリ情報
- リモートリポジトリURL

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| リモートURL | string | GitHub/GitLab等のファイルURL |
| 履歴情報 | list | コミット履歴データ |
| コンフリクトマーカー | overlay | コンフリクト箇所のハイライト |

### 出力先

- ブラウザ（browse-at-remote）
- 現在のバッファ（git-timemachine、smerge-mode）
- ヘッダーライン（git-timemachine revision info）

## 処理フロー

### 処理シーケンス

```
1. ファイルを開く
   └─ find-file-hookで+vc-init-smerge-mode-hを実行
2. コンフリクトマーカーを検出
   └─ 存在すればsmerge-modeを有効化
3. ユーザーがVC操作を実行
   └─ git-timemachine、browse-at-remote等
4. 結果を表示
   └─ バッファ更新、ブラウザ起動等
```

### フローチャート

```mermaid
flowchart TD
    A[ファイルを開く] --> B{コンフリクトマーカーあり?}
    B -->|Yes| C[smerge-mode有効化]
    B -->|No| D[通常編集]
    C --> E[コンフリクト解決操作]
    E --> F{解決完了?}
    F -->|Yes| G[ファイル保存]
    F -->|No| E

    H[git-timemachine起動] --> I[履歴取得]
    I --> J[リビジョン表示]
    J --> K{ナビゲーション}
    K -->|前へ| L[前のリビジョン]
    K -->|次へ| M[次のリビジョン]
    L --> J
    M --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-54-01 | VCバックエンド制限 | SVN, Git, Hgのみをサポート | 常時 |
| BR-54-02 | node_modules除外 | node_modulesディレクトリはVC操作から除外 | 常時 |
| BR-54-03 | パーマリンク優先 | browse-at-remoteはデフォルトでコミットハッシュを使用 | 常時 |
| BR-54-04 | detached HEAD対策 | detached状態ではmasterブランチにフォールバック | browse-at-remote使用時 |

### 計算ロジック

- リモートURL生成: `browse-at-remote--format-region-url-as-*`関数群
- コンフリクト検出: `^<<<<<<< `正規表現でマッチング

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

本機能はデータベース操作を行わない。Gitリポジトリを参照する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | リポジトリ未検出 | VCS管理外のファイル | user-errorを発生 |
| - | リモート未設定 | Gitリモートが未設定 | エラーメッセージ表示 |

### リトライ仕様

リトライ処理は不要。

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

トランザクション処理は不要（読み取り専用操作が主）。

## パフォーマンス要件

- vc-handled-backendsの最適化により、TRAMP経由でのVC操作を高速化
- node_modulesの除外により、大規模プロジェクトでのVC操作を高速化

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

- WindowsではGIT_ASKPASSを設定してパスワード入力を適切に処理

## 備考

- Emacs 28以降ではbug-reference-modeがVCからリポジトリ情報を自動取得
- Emacs 27以下ではバックポートされた機能を使用

---

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

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

### 推奨読解順序

#### Step 1: 基本設定を理解する

VC関連の基本設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/emacs/vc/config.el` | 基本設定（1-14行目） |

**読解のコツ**: `vc-handled-backends`で対応VCSを制限、`vc-ignore-dir-regexp`でnode_modulesを除外。

**主要処理フロー**:
1. **6行目**: VCバックエンドをSVN, Git, Hgに限定
2. **9-11行目**: node_modulesをVC操作から除外
3. **13-14行目**: Windows環境でのGIT_ASKPASS設定

#### Step 2: smerge-modeを理解する

コンフリクト解決機能の設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/emacs/vc/config.el` | smerge-mode設定（53-82行目） |

**主要処理フロー**:
- **56-62行目**: `+vc-init-smerge-mode-h`でコンフリクト自動検出
- **64-82行目**: ローカルリーダーキーマップの定義

#### Step 3: git-timemachineを理解する

ファイル履歴閲覧機能の設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/emacs/vc/config.el` | git-timemachine設定（85-150行目） |

**主要処理フロー**:
- **89行目**: ミニバッファに詳細表示を有効化
- **92-117行目**: browse-at-remoteとの統合
- **119-133行目**: ヘッダーラインにリビジョン情報を表示
- **146-150行目**: Evilキーマップの定義

#### Step 4: browse-at-remoteを理解する

リモートURL生成機能の設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/emacs/vc/config.el` | browse-at-remote設定（153-192行目） |
| 4-2 | autoload/vc.el | `modules/emacs/vc/autoload/vc.el` | コマンド定義（33-71行目） |

**主要処理フロー**:
- **157行目**: 選択なしでは行番号を含めない
- **160行目**: パーマリンク（コミットハッシュ）を優先
- **164-168行目**: Codeberg、GitLabサポートの追加

#### Step 5: bug-referenceバックポートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | autoload/bug-reference-backport.el | `modules/emacs/vc/autoload/bug-reference-backport.el` | バックポート実装（1-101行目） |

**主要処理フロー**:
- **9-67行目**: `bug-reference-setup-from-vc-alist`の定義
- **78-90行目**: `bug-reference-try-setup-from-vc`関数
- **93-100行目**: フック設定

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

```
find-file-hook
    │
    └─ +vc-init-smerge-mode-h
           │
           └─ smerge-mode (コンフリクト検出時)
                  │
                  ├─ smerge-next/prev
                  ├─ smerge-keep-upper/lower
                  └─ smerge-ediff

+vc/browse-at-remote
    │
    ├─ browse-at-remote--remote-ref
    ├─ browse-at-remote--get-url-from-remote
    └─ browse-url

git-timemachine
    │
    ├─ git-timemachine-show-previous-revision
    ├─ git-timemachine-show-next-revision
    └─ git-timemachine--show-minibuffer-details
           └─ setq header-line-format
```

### データフロー図

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

ファイル ───▶ vc-handled-backends ───▶ VCS検出
                      │
                      ▼
              Git/Hg/SVN操作
                      │
           ┌──────────┼──────────┐
           ▼          ▼          ▼
      smerge     timemachine  browse-at
           │          │          │
           ▼          ▼          ▼
      マージ解決   履歴表示    URL生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/emacs/vc/config.el` | ソース | メイン設定、パッケージ設定 |
| packages.el | `modules/emacs/vc/packages.el` | 設定 | 依存パッケージ定義 |
| autoload/vc.el | `modules/emacs/vc/autoload/vc.el` | ソース | browse-at-remoteコマンド定義 |
| autoload/bug-reference-backport.el | `modules/emacs/vc/autoload/bug-reference-backport.el` | ソース | Emacs 27用バックポート |
