# 機能設計書 22-git_prompt_info

## 概要

本ドキュメントは、Oh My Zshの`git_prompt_info`関数の機能設計を定義するものである。この関数は、現在のGitブランチ名とワーキングツリーの状態（ダーティ/クリーン）をプロンプト表示用にフォーマットして出力する機能を提供する。

### 本機能の処理概要

`git_prompt_info`関数は、Gitリポジトリ内で現在のブランチ名やタグ名、コミットSHAを取得し、ワーキングツリーの状態（変更あり/なし）と組み合わせて、テーマ変数でカスタマイズ可能な形式でプロンプト文字列を生成する。

**業務上の目的・背景**：開発者がターミナルで作業する際、現在どのGitブランチにいるか、未コミットの変更があるかを常に把握できることは非常に重要である。この関数により、プロンプトに常にGit情報を表示することで、ブランチの切り替え忘れや意図しないコミットを防ぐことができる。

**機能の利用シーン**：
- シェルのプロンプトにGitブランチ情報を表示したい場合
- ワーキングツリーの状態（変更あり/なし）を視覚的に確認したい場合
- テーマをカスタマイズしてGit情報の表示形式を変更したい場合

**主要な処理内容**：
1. Gitリポジトリ内かどうかを判定
2. `oh-my-zsh.hide-info`設定による非表示制御をチェック
3. 現在のブランチ名、タグ名、または短縮SHAを取得
4. オプションでupstreamリモート情報を取得
5. `parse_git_dirty`関数でワーキングツリーの状態を取得
6. テーマ変数を使用してフォーマットされた文字列を出力

**関連システム・外部連携**：
- Gitコマンド（`git symbolic-ref`、`git describe`、`git rev-parse`）
- `parse_git_dirty`関数（No.24）との連携
- 非同期プロンプトシステム（`_omz_register_handler`）との統合

**権限による制御**：特になし。Gitリポジトリへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | シェルプロンプト | 主画面 | プロンプト表示時にGit情報を出力 |

## 機能種別

情報取得・フォーマット処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | この関数は引数を取らない | - |

### 入力データソース

- カレントディレクトリのGitリポジトリ情報
- テーマ変数（`ZSH_THEME_GIT_PROMPT_PREFIX`、`ZSH_THEME_GIT_PROMPT_SUFFIX`等）
- Git設定（`oh-my-zsh.hide-info`、`ZSH_THEME_GIT_SHOW_UPSTREAM`）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| プロンプト文字列 | 文字列 | `${PREFIX}${ref}${upstream}${dirty/clean}${SUFFIX}`形式の文字列 |

### 出力先

標準出力（プロンプト表示用）

## 処理フロー

### 処理シーケンス

```
1. Gitリポジトリ判定
   └─ git rev-parse --git-dir でGitリポジトリかチェック
2. 非表示設定チェック
   └─ oh-my-zsh.hide-info が1の場合は空文字を返す
3. 参照名（ref）の取得
   └─ 優先順位: ブランチ名 → タグ名 → 短縮SHA
4. upstream情報の取得（オプション）
   └─ ZSH_THEME_GIT_SHOW_UPSTREAMが設定されている場合
5. ダーティ/クリーン状態の取得
   └─ parse_git_dirty関数を呼び出し
6. フォーマット文字列の生成と出力
   └─ テーマ変数を使用して結果を構築
```

### フローチャート

```mermaid
flowchart TD
    A[開始: git_prompt_info] --> B{Gitリポジトリ内?}
    B -->|No| C[空文字を返して終了]
    B -->|Yes| D{hide-info=1?}
    D -->|Yes| C
    D -->|No| E[ブランチ名を取得]
    E --> F{取得成功?}
    F -->|No| G[タグ名を取得]
    G --> H{取得成功?}
    H -->|No| I[短縮SHAを取得]
    H -->|Yes| J[refにタグ名を設定]
    I --> K{取得成功?}
    K -->|No| C
    K -->|Yes| L[refに短縮SHAを設定]
    F -->|Yes| M[refにブランチ名を設定]
    J --> N{SHOW_UPSTREAM設定?}
    L --> N
    M --> N
    N -->|Yes| O[upstream情報を取得]
    N -->|No| P[parse_git_dirtyを呼び出し]
    O --> P
    P --> Q[フォーマット文字列を生成]
    Q --> R[結果を出力]
    R --> S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-01 | ref取得優先順位 | ブランチ名 → タグ名 → 短縮SHAの順で取得を試みる | 常時 |
| BR-22-02 | 非表示制御 | `oh-my-zsh.hide-info=1`の場合は何も出力しない | hide-info設定時 |
| BR-22-03 | upstream表示 | `ZSH_THEME_GIT_SHOW_UPSTREAM`設定時のみupstream情報を表示 | 設定時 |
| BR-22-04 | エスケープ処理 | ref名の`%`文字は`%%`にエスケープする | 常時 |

### 計算ロジック

該当なし

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

### 操作別データベース影響一覧

該当なし（データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非Gitリポジトリ | Gitリポジトリ外で実行 | 空文字を返す |
| - | ref取得失敗 | ブランチ、タグ、SHAすべて取得できない | 空文字を返す |

### リトライ仕様

リトライ機能なし

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

該当なし

## パフォーマンス要件

- `GIT_OPTIONAL_LOCKS=0`を設定してGitコマンドを実行し、ロック競合を回避
- 非同期プロンプトモードでの実行をサポートし、プロンプト表示の遅延を防止

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

- 読み取り専用のGit操作のみを実行
- `GIT_OPTIONAL_LOCKS=0`によりファイルロックを取得しない

## 備考

- zsh 5.0.6以上では非同期プロンプトモードがデフォルトで有効
- テーマ変数でプレフィックス、サフィックス、ダーティ/クリーンマーカーをカスタマイズ可能

---

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

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

### 推奨読解順序

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

まず、この機能で使用されるテーマ変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | テーマファイル | `themes/*.zsh-theme` | ZSH_THEME_GIT_PROMPT_* 変数の定義を確認 |

**主要なテーマ変数**:
- `ZSH_THEME_GIT_PROMPT_PREFIX`: ブランチ名の前に表示する文字列
- `ZSH_THEME_GIT_PROMPT_SUFFIX`: ブランチ名の後に表示する文字列
- `ZSH_THEME_GIT_PROMPT_DIRTY`: 変更ありの場合に表示するマーカー
- `ZSH_THEME_GIT_PROMPT_CLEAN`: 変更なしの場合に表示するマーカー
- `ZSH_THEME_GIT_SHOW_UPSTREAM`: upstreamリモート情報を表示するかどうか

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | git.zsh | `lib/git.zsh` | git_prompt_info関数の実装を確認 |

**主要処理フロー**:
1. **10-12行目**: `__git_prompt_git`関数 - `GIT_OPTIONAL_LOCKS=0`でgitコマンドを実行
2. **14-40行目**: `_omz_git_prompt_info`関数 - メインのGitプロンプト情報取得ロジック
3. **17-20行目**: Gitリポジトリ判定と`hide-info`設定チェック
4. **26-30行目**: ref（ブランチ名/タグ名/SHA）の取得
5. **33-37行目**: upstream情報の取得（オプション）
6. **39行目**: 最終的な出力文字列の構築

**読解のコツ**:
- `symbolic-ref --short HEAD`はブランチ名を取得
- `describe --tags --exact-match HEAD`はタグ名を取得
- `rev-parse --short HEAD`は短縮SHAを取得

#### Step 3: 非同期プロンプト対応を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | git.zsh | `lib/git.zsh` | 非同期/同期の切り替えロジック |

**主要処理フロー**:
- **146-148行目**: zstyle設定またはzshバージョンによる非同期モード判定
- **149-153行目**: 非同期モードの`git_prompt_info`関数定義
- **163-179行目**: `_defer_async_git_register`関数 - プロンプト変数をチェックして必要に応じてハンドラ登録
- **200-202行目**: 同期モードの`git_prompt_info`関数定義

#### Step 4: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | git.zsh | `lib/git.zsh` | parse_git_dirty関数（209-234行目） |

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

```
git_prompt_info (ユーザー呼び出し/プロンプト展開)
    │
    ├─【非同期モード】
    │   └─ _OMZ_ASYNC_OUTPUT[_omz_git_prompt_info] から結果を取得
    │
    └─【同期モード】
        └─ _omz_git_prompt_info (lib/git.zsh:14-40)
               │
               ├─ __git_prompt_git rev-parse --git-dir
               │      └─ Gitリポジトリ判定
               │
               ├─ __git_prompt_git config --get oh-my-zsh.hide-info
               │      └─ 非表示設定チェック
               │
               ├─ __git_prompt_git symbolic-ref --short HEAD
               │      └─ ブランチ名取得
               │
               ├─ __git_prompt_git describe --tags --exact-match HEAD
               │      └─ タグ名取得（ブランチ名取得失敗時）
               │
               ├─ __git_prompt_git rev-parse --short HEAD
               │      └─ 短縮SHA取得（タグ名取得失敗時）
               │
               ├─ __git_prompt_git rev-parse --abbrev-ref --symbolic-full-name @{upstream}
               │      └─ upstream情報取得（オプション）
               │
               └─ parse_git_dirty (lib/git.zsh:209-234)
                      └─ ダーティ/クリーン状態判定
```

### データフロー図

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

カレントディレクトリ ──▶ git rev-parse --git-dir ──▶ リポジトリ判定
                              │
                              ▼
Git設定 ──────────────▶ config --get hide-info ──▶ 表示/非表示
                              │
                              ▼
                        symbolic-ref HEAD ──────▶ ブランチ名
                        または describe --tags ──▶ タグ名
                        または rev-parse --short ─▶ 短縮SHA
                              │
                              ▼
ZSH_THEME_GIT_SHOW_UPSTREAM ─▶ upstream情報取得 ──▶ "-> remote/branch"
                              │
                              ▼
                        parse_git_dirty ────────▶ DIRTY/CLEAN マーカー
                              │
                              ▼
テーマ変数 ───────────▶ 文字列構築 ────────────▶ "${PREFIX}${ref}${upstream}${dirty}${SUFFIX}"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| git.zsh | `lib/git.zsh` | ソース | Git関連プロンプト関数の実装 |
| async_prompt.zsh | `lib/async_prompt.zsh` | ソース | 非同期プロンプト処理の基盤 |
| *.zsh-theme | `themes/*.zsh-theme` | テーマ | テーマ変数の定義とプロンプトでの使用 |
