# 機能設計書 65-Gitクライアント統合

## 概要

本ドキュメントは、Doom EmacsにおけるGitクライアント統合モジュール（magit）の機能設計を記述する。本モジュールはMagitをベースとしたGit操作機能を提供し、GitHub/GitLab連携（Forge）やコードレビュー機能も含む。

### 本機能の処理概要

Gitクライアント統合モジュールは、Magitを中核としてGitリポジトリの操作、履歴閲覧、ブランチ管理、コミット作成などの機能を提供する。さらにForge連携によりGitHub/GitLabのIssue、Pull Request管理機能を統合し、code-reviewによるPRレビュー機能も提供する。

**業務上の目的・背景**：
バージョン管理はソフトウェア開発の中核であり、効率的なGit操作は開発生産性に直結する。コマンドラインでのGit操作は強力だが、複雑な操作や履歴の視覚化には限界がある。本モジュールは、Magitの直感的なUIを通じてGit操作を効率化し、さらにGitHub/GitLabとの連携により、Issue管理やPRレビューをEmacs内で完結させる。

**機能の利用シーン**：
- コード変更のステージング・コミット作成
- ブランチの作成・マージ・リベース
- 変更履歴の閲覧・差分確認
- GitHub Issue/PRの作成・管理
- Pull Requestのコードレビュー

**主要な処理内容**：
1. magit-status によるリポジトリ状態表示
2. ステージング・アンステージング操作
3. コミット作成・履歴表示
4. ブランチ操作（作成、切り替え、マージ、リベース）
5. リモート操作（fetch、pull、push）
6. Forge連携（Issue/PR管理）
7. バッファ自動リバート（Git操作後）

**関連システム・外部連携**：
- magit：Git porcelain
- forge：GitHub/GitLab/Gitea連携
- transient：メニューUI
- git-commit：コミットメッセージ編集

**権限による制御**：
本機能に権限による制御は存在しない。ただし、Forge機能はGitHub/GitLabのAPI認証が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Treemacs | 補助機能 | treemacs-magit連携、Git差分表示 |
| 10 | Workspaces | 補助機能 | magit-status-modeの保存・復元 |
| 12 | Modeline | 補助機能 | Gitブランチ、差分情報表示 |

## 機能種別

バージョン管理 / Git操作 / GitHub/GitLab連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +magit-open-windows-in-direction | symbol | No | 新規ウィンドウの開く方向（デフォルト:'right） | 'left, 'right, 'up, 'down |
| +magit-fringe-size | integer/cons | No | フリンジサイズ（デフォルト:(13 . 1)） | 正の整数またはcons cell |
| +magit-auto-revert | symbol/function | No | 自動リバート設定（デフォルト:'local） | t, 'local, nil, 関数 |

### 入力データソース

- Gitリポジトリ（.git/ディレクトリ）
- GitHub/GitLab API（Forge使用時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| magit-status-buffer | buffer | リポジトリ状態表示バッファ |
| magit-diff-buffer | buffer | 差分表示バッファ |
| magit-log-buffer | buffer | 履歴表示バッファ |
| forge-database | sqlite | Forge情報キャッシュ |

### 出力先

- Magit各種バッファ
- Forgeデータベース（doom-profile-data-dir配下）
- transientパラメータファイル

## 処理フロー

### 処理シーケンス

```
1. magit-status コマンド呼び出し
   └─ Gitリポジトリ検出

2. ステータスバッファ表示
   ├─ Untracked files
   ├─ Unstaged changes
   ├─ Staged changes
   └─ Recent commits

3. 操作実行（ステージング、コミット等）
   └─ magit-post-refresh-hook 発火

4. 自動リバート処理
   ├─ 可視バッファを即時リバート
   └─ 非可視バッファをstale状態に
```

### フローチャート

```mermaid
flowchart TD
    A[magit-status] --> B[リポジトリ検出]
    B --> C{リポジトリ存在?}
    C -->|No| X[エラー]
    C -->|Yes| D[ステータスバッファ作成]
    D --> E[セクション描画]
    E --> F[ユーザー操作待機]
    F --> G{操作種別}
    G -->|ステージング| H[git add/reset]
    G -->|コミット| I[git-commit-mode]
    G -->|プッシュ| J[git push]
    G -->|その他| K[対応操作]
    H --> L[バッファリフレッシュ]
    I --> L
    J --> L
    K --> L
    L --> M[自動リバート処理]
    M --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 自動リバート | Git操作後、関連バッファを自動リバート | +magit-auto-revert が non-nil |
| BR-02 | ローカルのみリバート | リモートファイルはリバート対象外 | +magit-auto-revert = 'local |
| BR-03 | バッファ重複防止 | 同一プロジェクトのステータスバッファは1つ | magit-uniquify-buffer-names = nil |
| BR-04 | projectileキャッシュ無効化 | Git操作後にprojectileキャッシュをクリア | magit-refresh-buffer-hook |
| BR-05 | ウィンドウ位置維持 | ステージング操作後のウィンドウ位置を維持 | magit-pre/post-refresh-hook |

### 計算ロジック

特になし。

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

### Forgeデータベース

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Forge初期化 | forge-database.sqlite | CREATE | データベース作成 |
| Issue/PR取得 | forge-database.sqlite | INSERT/UPDATE | GitHub/GitLabからのデータ同期 |

### transient履歴

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 履歴保存 | transient/history | WRITE | コマンド履歴の保存 |
| 値保存 | transient/values | WRITE | パラメータ値の保存 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | リポジトリ未検出 | .gitディレクトリがない | エラーメッセージ表示 |
| - | Git未インストール | gitコマンドが見つからない | doctor.elで検出 |
| - | Forge認証エラー | GitHub/GitLabトークン未設定 | 認証設定案内 |

### リトライ仕様

特になし。

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

Git操作はatomicではないが、Magitは操作の途中状態を適切に表示する。

## パフォーマンス要件

- magit-auto-revert-modeは使用しない（独自実装による最適化）
- magit-revision-insert-related-refs = nil（パフォーマンス向上）
- magit-save-repository-buffers = nil（意図しない保存を防止）

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

- Forgeトークンはauthinfo/authinfo.gpgで管理
- Forgeデータベースはdoom-profile-data-dir配下に隔離

## 備考

- +forgeフラグでGitHub/GitLab連携を有効化
- Emacs 29.1以降でForge機能が利用可能

---

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

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

### 推奨読解順序

#### Step 1: 設定変数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/tools/magit/config.el` | カスタム変数定義（3-35行目） |

**読解のコツ**:
- `+magit-open-windows-in-direction`: ウィンドウ分割方向
- `+magit-fringe-size`: フリンジサイズ
- `+magit-auto-revert`: 自動リバート設定

#### Step 2: Magit設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/tools/magit/config.el` | magit use-package設定（41-174行目） |

**主要処理フロー**:
- **53-69行目**: パフォーマンス設定（magit-diff-refine-hunk等）
- **76-85行目**: projectileキャッシュ無効化フック
- **87-93行目**: 自動リバート処理フック設定
- **111-128行目**: ウィンドウ表示設定

#### Step 3: 自動リバート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload.el | `modules/tools/magit/autoload.el` | 自動リバート関数（99-149行目） |

**主要処理フロー**:
- **101-110行目**: +magit--revertable-buffer-p でリバート対象判定
- **112-126行目**: +magit--revert-buffer でリバート実行
- **128-143行目**: +magit-mark-stale-buffers-h で可視/非可視バッファ処理
- **145-149行目**: +magit-revert-buffer-maybe-h でstaleバッファのリバート

#### Step 4: ウィンドウ表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload.el | `modules/tools/magit/autoload.el` | +magit-display-buffer-fn（14-93行目） |

**主要処理フロー**:
- **20-61行目**: バッファ種別による表示方法の分岐
- **63-93行目**: +magit--display-buffer-in-direction

#### Step 5: Forge連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/tools/magit/config.el` | forge use-package（177-199行目） |
| 5-2 | config.el | `modules/tools/magit/config.el` | code-review設定（202-222行目） |

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

```
magit-status
    │
    ├─ +magit-display-buffer-fn
    │      └─ +magit--display-buffer-in-direction
    │
    └─ magit-refresh-buffer-hook
           │
           ├─ +magit-invalidate-projectile-cache-h
           │      └─ projectile-invalidate-cache
           │
           └─ +magit-mark-stale-buffers-h
                  │
                  ├─ [可視バッファ]
                  │      └─ +magit--revert-buffer
                  │
                  └─ [非可視バッファ]
                         └─ setq +magit--stale-p t

doom-switch-buffer-hook
    └─ +magit-revert-buffer-maybe-h
           └─ +magit--revert-buffer
```

### データフロー図

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

Gitリポジトリ ───▶ magit-status ───▶ ステータスバッファ
                        │
                        ▼
              ┌────────────────┐
              │ユーザー操作    │
              │(ステージング等)│
              └────────────────┘
                        │
                        ▼
               Git操作実行
                        │
            ┌───────────┴───────────┐
            ▼                       ▼
   バッファリフレッシュ      自動リバート処理
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/magit/config.el` | ソース | メイン設定、magit/forge/code-review |
| autoload.el | `modules/tools/magit/autoload.el` | ソース | 表示関数、自動リバート、コマンド |
| doctor.el | `modules/tools/magit/doctor.el` | 診断 | Git/ghub/forge診断 |
| packages.el | `modules/tools/magit/packages.el` | 設定 | 依存パッケージ定義 |
