# 機能設計書 31-git_prompt_long_sha

## 概要

本ドキュメントは、Oh My Zshの`git_prompt_long_sha`関数の機能設計について記載する。この関数は、現在のGitリポジトリにおけるHEADコミットのフルSHA（40文字）を取得し、プロンプト表示用にフォーマットして出力する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Gitを使用した開発作業において、現在作業中のコミットを正確に特定することは重要である。短縮SHAでは衝突の可能性があるため、完全なコミットSHAが必要な場面（CI/CD連携、デバッグ、監査ログ等）において、プロンプトからフルSHAを即座に確認できることは作業効率を向上させる。

**機能の利用シーン**：開発者がターミナルで作業する際、プロンプトに現在のコミットSHAを表示したいケースで利用される。特に、複数のブランチやコミットを頻繁に切り替える作業や、特定のコミットで発生した問題をデバッグする際に有用である。

**主要な処理内容**：
1. `git rev-parse HEAD`コマンドを実行してフルSHA（40文字）を取得
2. 取得したSHAをテーマ変数（`ZSH_THEME_GIT_PROMPT_SHA_BEFORE`、`ZSH_THEME_GIT_PROMPT_SHA_AFTER`）でラップ
3. フォーマットされた文字列を標準出力に出力

**関連システム・外部連携**：Gitコマンドラインツールと連携し、リポジトリ情報を取得する。

**権限による制御**：特になし。Gitリポジトリへの読み取りアクセス権があれば実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ターミナルプロンプト | 結果表示画面 | プロンプト変数（$PROMPT、$RPROMPT等）に組み込んで使用 |

## 機能種別

データ取得・フォーマット処理

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- **Gitリポジトリ**: カレントディレクトリまたはその親ディレクトリにある`.git`ディレクトリ
- **環境変数**:
  - `ZSH_THEME_GIT_PROMPT_SHA_BEFORE`: SHA表示の前に付与する文字列（テーマで定義）
  - `ZSH_THEME_GIT_PROMPT_SHA_AFTER`: SHA表示の後に付与する文字列（テーマで定義）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| フォーマット済みSHA文字列 | string | `${ZSH_THEME_GIT_PROMPT_SHA_BEFORE}${SHA}${ZSH_THEME_GIT_PROMPT_SHA_AFTER}`形式の文字列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. git rev-parse HEADを実行
   └─ __git_prompt_git関数を使用してGIT_OPTIONAL_LOCKS=0環境変数付きで実行
2. 結果の判定
   └─ コマンドが成功した場合のみ次のステップへ
3. フォーマット出力
   └─ ZSH_THEME_GIT_PROMPT_SHA_BEFORE + SHA + ZSH_THEME_GIT_PROMPT_AFTER を連結してecho
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[git rev-parse HEAD実行]
    B --> C{コマンド成功?}
    C -->|Yes| D[SHA変数に格納]
    D --> E[テーマ変数でラップして出力]
    E --> F[終了]
    C -->|No| F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-31-1 | Gitリポジトリ必須 | Gitリポジトリ外で実行した場合は何も出力しない | 常時 |
| BR-31-2 | フルSHA取得 | 短縮SHAではなく40文字のフルSHAを取得する | 常時 |
| BR-31-3 | テーマ変数使用 | 出力はテーマ定義の前後文字列でラップされる | テーマ変数が定義されている場合 |

### 計算ロジック

特になし

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

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

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 暗黙のエラー | Gitリポジトリが存在しない | 何も出力しない（正常終了） |
| - | 暗黙のエラー | HEADが存在しない（空リポジトリ） | 何も出力しない（正常終了） |

### リトライ仕様

リトライは実装されていない

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

該当なし

## パフォーマンス要件

プロンプト表示に使用されるため、可能な限り高速に実行される必要がある。`GIT_OPTIONAL_LOCKS=0`環境変数を設定することで、gitコマンドがロックを取得しないようにしている。

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

- `__git_prompt_git`ラッパー関数を使用して`GIT_OPTIONAL_LOCKS=0`を設定し、他のgitプロセスとの干渉を防止
- 標準エラー出力は`/dev/null`にリダイレクトしてエラーメッセージを非表示

## 備考

- `git_prompt_short_sha`関数と対になる機能で、短縮SHA（7文字）ではなくフルSHA（40文字）を返す
- テーマでの使用例: `PROMPT='$(git_prompt_long_sha) '`

---

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

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

### 推奨読解順序

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

この関数はシンプルで、主要なデータ構造は環境変数のみである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | git.zsh | `lib/git.zsh` | テーマ変数（`ZSH_THEME_GIT_PROMPT_SHA_*`）の使用方法を確認 |

**読解のコツ**: ZSHの変数展開`${VAR}`と条件付き実行`&&`を理解することが重要。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | git.zsh | `lib/git.zsh` | `git_prompt_long_sha`関数の定義（343-346行目） |

**主要処理フロー**:
1. **343行目**: 関数定義開始
2. **344行目**: ローカル変数SHAの宣言
3. **345行目**: `__git_prompt_git rev-parse HEAD`でフルSHAを取得し、成功時にテーマ変数付きで出力
4. **346行目**: 関数定義終了

#### Step 3: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | git.zsh | `lib/git.zsh` | `__git_prompt_git`関数（10-12行目）の役割 |

**主要処理フロー**:
- **11行目**: `GIT_OPTIONAL_LOCKS=0`を設定してgitコマンドを実行

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

```
git_prompt_long_sha()
    │
    └─ __git_prompt_git rev-parse HEAD
           │
           └─ command git rev-parse HEAD (GIT_OPTIONAL_LOCKS=0環境変数付き)
```

### データフロー図

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

なし ───────▶ git rev-parse HEAD ───────▶ フォーマット済みSHA文字列
                      │                        │
                      ▼                        ▼
               40文字のフルSHA            $ZSH_THEME_GIT_PROMPT_SHA_BEFORE
                                         + SHA
                                         + $ZSH_THEME_GIT_PROMPT_SHA_AFTER
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| git.zsh | `lib/git.zsh` | ソース | git_prompt_long_sha関数の定義元 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/git.zshを読み込むメインスクリプト |
