# 機能設計書 18-omz version

## 概要

本ドキュメントは、Oh My Zshの`omz version`コマンドの機能設計について記載する。このコマンドは現在インストールされているOh My Zshのバージョン情報を表示する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Oh My Zshのユーザーやサポート担当者が、現在インストールされているバージョンを確認することは、トラブルシューティングやアップデート判断において重要である。本機能は、gitリポジトリの情報を基に、タグ、ブランチ名、コミットハッシュを組み合わせたバージョン情報を提供する。

**機能の利用シーン**：
- 現在のOh My Zshバージョンを確認したい場合
- バグ報告時にバージョン情報を取得したい場合
- アップデートが必要かどうかを判断する際の参考情報として
- カスタマーサポートやコミュニティでの問い合わせ時

**主要な処理内容**：
1. `$ZSH`ディレクトリに移動
2. `git describe --tags`でタグベースのバージョン名を取得
3. 取得できない場合は`git symbolic-ref`でブランチ名を取得
4. それも取得できない場合は`git name-rev`で参照名を取得
5. 短縮コミットハッシュ（7文字）を取得
6. バージョン名とコミットハッシュを組み合わせて出力

**関連システム・外部連携**：gitリポジトリの情報を参照する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | omz version | 主画面 | 現在のOMZバージョン（gitタグ/ブランチ + commit SHA）を表示 |

## 機能種別

データ参照・情報表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | パラメータなし | - |

### 入力データソース

- `$ZSH`ディレクトリ内のgitリポジトリ情報
- gitタグ
- gitブランチ
- gitコミットハッシュ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| version | 文字列 | バージョン名（タグ、ブランチ名、または参照名） |
| commit | 文字列 | 短縮コミットハッシュ（7文字） |

### 出力先

- 標準出力: `バージョン名 (コミットハッシュ)`形式

### 出力形式

```
master (abc1234)
```

または

```
v1.0.0-123-g456789a (456789a)
```

## 処理フロー

### 処理シーケンス

```
1. $ZSHディレクトリに移動
   └─ builtin cd -q "$ZSH"

2. バージョン名の取得（優先順位順）
   ├─ git describe --tags HEAD → タグベースのバージョン
   ├─ git symbolic-ref --quiet --short HEAD → ブランチ名
   ├─ git name-rev --no-undefined --name-only HEAD → 参照名
   └─ "<detached>" → どれも取得できない場合

3. コミットハッシュの取得
   └─ git rev-parse --short HEAD → 短縮ハッシュ（7文字）

4. 出力
   └─ printf "%s (%s)\n" "$version" "$commit"
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[cd $ZSH]
    B --> C{git describe --tags HEAD}
    C -->|成功| D[version = タグベース名]
    C -->|失敗| E{git symbolic-ref HEAD}
    E -->|成功| F[version = ブランチ名]
    E -->|失敗| G{git name-rev HEAD}
    G -->|成功| H[version = 参照名]
    G -->|失敗| I["version = <detached>"]
    D --> J[git rev-parse --short HEAD]
    F --> J
    H --> J
    I --> J
    J --> K[commit = 短縮ハッシュ]
    K --> L["出力: version (commit)"]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | タグ優先 | `git describe --tags`でタグベースのバージョンを最優先で取得 | 常時 |
| BR-02 | ブランチフォールバック | タグがない場合は現在のブランチ名を使用 | タグ取得失敗時 |
| BR-03 | 参照名フォールバック | ブランチ名も取得できない場合は`name-rev`で参照名を使用 | ブランチ取得失敗時 |
| BR-04 | detached表示 | どの参照も取得できない場合は`<detached>`と表示 | 全取得失敗時 |
| BR-05 | リモート除外 | `name-rev`では`remotes/*`パターンを除外 | 参照名取得時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | gitリポジトリ外 | $ZSHがgitリポジトリでない | コマンドは失敗するがエラーメッセージは出力されない |

### リトライ仕様

リトライは行わない。

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

該当なし（読み取り専用操作）。

## パフォーマンス要件

- 即座に実行されること（通常数百ミリ秒以内）
- gitコマンドの実行時間に依存

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

- gitリポジトリの読み取り権限のみを使用
- 情報の表示のみで、リポジトリへの書き込みは行わない

## 備考

- サブシェル内で実行されるため、現在の作業ディレクトリに影響を与えない
- `git describe --tags`はコミット数も含めた詳細なバージョン情報を提供（例: `v1.0.0-123-g456789a`）
- HEADがタグを直接指している場合はタグ名のみが表示される

---

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

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

### 推奨読解順序

#### Step 1: 関数の全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | `_omz::version`関数の定義位置（924-944行目）を確認 |

**読解のコツ**: この関数はサブシェル`( )`内で実行される。`||`演算子によるフォールバックチェーンに注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | omz関数（3-21行目）からのコマンドディスパッチを確認 |

**主要処理フロー**:
1. **3-21行目**: `omz`関数がコマンドライン引数を解析し、`_omz::$command`を呼び出す
2. **924-944行目**: `_omz::version`関数が直接呼び出される

#### Step 3: gitコマンドの詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | `_omz::version`関数内のgitコマンド群 |

**主要処理フロー**:
- **925行目**: サブシェルの開始
- **926行目**: `$ZSH`ディレクトリへの移動
- **928-936行目**: バージョン名の取得（フォールバックチェーン）
- **939行目**: 短縮コミットハッシュの取得
- **942行目**: フォーマットされた出力

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

```
omz (3-21行目)
    │
    └─ _omz::version (924-944行目)
           │
           └─ (サブシェル)
                  │
                  ├─ cd "$ZSH"
                  │
                  ├─ git describe --tags HEAD
                  │      └─ (失敗時) git symbolic-ref HEAD
                  │             └─ (失敗時) git name-rev HEAD
                  │                    └─ (失敗時) "<detached>"
                  │
                  ├─ git rev-parse --short HEAD
                  │
                  └─ printf "%s (%s)\n"
```

### データフロー図

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

$ZSH              ───▶ cd $ZSH
                          │
git refs          ───▶ バージョン名取得
                          │
                          ├─ git describe --tags
                          ├─ git symbolic-ref
                          ├─ git name-rev
                          └─ "<detached>"
                               │
                               ▼
git HEAD          ───▶ git rev-parse --short     ───▶ "version (commit)"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドのCLI実装。_omz::version関数を含む |
