# 画面設計書 15-omz version

## 概要

本ドキュメントは、Oh My Zshのバージョン情報を表示するCLIコマンド `omz version` の画面設計書です。

### 本画面の処理概要

`omz version` コマンドは、現在インストールされているOh My Zshのバージョン情報を表示するためのコマンドインターフェースです。

**業務上の目的・背景**：Oh My Zshのトラブルシューティングやバグ報告の際に、現在使用しているバージョンを正確に把握する必要があります。本コマンドは、gitタグ、ブランチ名、コミットハッシュを組み合わせて、現在のOh My Zshの正確なバージョン情報を提供します。これにより、ユーザーは自分の環境を正確に特定し、問題報告やサポート依頼時に必要な情報を得ることができます。

**画面へのアクセス方法**：ターミナルで `omz version` を実行することでアクセスします。

**主要な操作・処理内容**：
1. $ZSHディレクトリに移動
2. gitタグからバージョン名を取得（git describe）
3. タグがない場合はブランチ名を取得（git symbolic-ref）
4. ブランチ名も取得できない場合はname-revで代替
5. いずれも失敗した場合は "<detached>" を表示
6. 短縮コミットハッシュを取得（git rev-parse --short）
7. バージョン名とコミットハッシュを組み合わせて出力

**画面遷移**：
- 遷移元: omzコマンドのサブコマンドとして呼び出し
- 遷移先: なし（情報表示のみ）

**権限による表示制御**：特になし。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてバージョンを表示 |
| 18 | omz version | 主機能 | 現在のOMZバージョン（gitタグ/ブランチ + commit SHA）を表示 |

## 画面種別

コマンドラインインターフェース（表示のみ）

## URL/ルーティング

```
omz version
```

引数は不要です。

## 入出力項目

### 入力項目

なし

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| バージョン情報 | テキスト | バージョン名とコミットハッシュ |

## 表示項目

| 表示項目 | 表示条件 | 説明 |
|----------|----------|------|
| バージョン名 | 常時 | gitタグ、ブランチ名、または"<detached>" |
| コミットハッシュ | 常時 | 短縮形式のコミットSHA |

### 出力形式

```
<バージョン名> (<コミットハッシュ>)
```

例:
- `master (abc1234)` - masterブランチ上の場合
- `v1.0.0 (def5678)` - タグがある場合
- `v1.0.0-5-gabc1234 (abc1234)` - タグからの距離がある場合
- `<detached> (xyz9999)` - detached HEAD状態の場合

## イベント仕様

### 1-バージョン名取得

gitコマンドを使用してバージョン名を取得します。優先順位は以下の通りです。

1. **git describe --tags HEAD**: タグベースのバージョン名
   - 成功例: `v1.0.0` または `v1.0.0-5-gabc1234`（タグから5コミット先）
2. **git symbolic-ref --quiet --short HEAD**: 現在のブランチ名
   - 成功例: `master`
3. **git name-rev --no-undefined --name-only --exclude="remotes/*" HEAD**: コミットの名前参照
   - 成功例: `master~3`（masterから3コミット戻った位置）
4. **"<detached>"**: 上記全て失敗時のフォールバック

### 2-コミットハッシュ取得

現在のHEADの短縮コミットハッシュを取得します。

- `git rev-parse --short HEAD` を実行
- 通常7文字程度の短縮形式

### 3-出力生成

取得した情報を整形して出力します。

- printf "%s (%s)\n" "$version" "$commit"
- 括弧内にコミットハッシュを表示

## データベース更新仕様

本コマンドはデータベースを使用しません。読み取り専用の操作のみを行います。

## メッセージ仕様

| 種別 | メッセージ例 | 表示条件 |
|------|-------------|----------|
| 出力 | "master (abc1234)" | ブランチ上の場合 |
| 出力 | "v1.0.0 (def5678)" | タグがある場合 |
| 出力 | "<detached> (xyz9999)" | detached HEAD時 |

## 例外処理

| 例外状態 | 処理内容 |
|----------|----------|
| gitリポジトリでない | gitコマンドがエラーを出力 |
| HEADが存在しない | gitコマンドがエラーを出力 |
| detached HEAD | "<detached>" を表示して正常終了 |

## 備考

- バージョン情報はgitリポジトリの状態に基づいています
- タグがない場合（通常のユーザー環境）はブランチ名が表示されます
- git describeは最も近いタグからの距離も表示します
- 本コマンドはサブシェル内で実行されるため、$ZSHへのcdは元のディレクトリに影響しません

---

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

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

### 推奨読解順序

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

まず、バージョン情報の構成要素を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | version変数とcommit変数の役割 |

**読解のコツ**: zshの `||` によるフォールバックチェーンを理解してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | omz関数（3-21行目）がエントリーポイント |

**主要処理フロー**:
1. **行3-8**: コマンドライン引数の確認
2. **行15-18**: サブコマンド関数の存在確認
3. **行20**: _omz::versionを呼び出し

#### Step 3: versionコマンドの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | `_omz::version`関数（924-944行目）がメインの実装 |

**主要処理フロー**:
- **行925-926**: サブシェル開始、$ZSHへ移動
- **行928-936**: バージョン名の取得（フォールバックチェーン）
  - **行933**: git describe --tags
  - **行934**: git symbolic-ref
  - **行935**: git name-rev
  - **行936**: "<detached>" フォールバック
- **行939**: コミットハッシュの取得
- **行942**: フォーマット出力

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

```
omz version
    │
    ├─ omz [lib/cli.zsh:3-21]
    │      └─ _omz::version [lib/cli.zsh:924-944]
    │             │
    │             ├─ (サブシェル)
    │             │      ├─ cd "$ZSH"
    │             │      ├─ git describe --tags HEAD
    │             │      ├─ git symbolic-ref --quiet --short HEAD
    │             │      ├─ git name-rev --no-undefined --name-only HEAD
    │             │      ├─ git rev-parse --short HEAD
    │             │      └─ printf (出力)
    │             │
    │             └─ 出力: "version (commit)"
    │
    └─ _omz [lib/cli.zsh:23-112] (補完関数)
```

### データフロー図

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

(なし) ─────────▶ cd $ZSH
                        │
                        ▼
                  git describe --tags ─────────────▶ version (成功時)
                        │ (失敗)
                        ▼
                  git symbolic-ref ────────────────▶ version (成功時)
                        │ (失敗)
                        ▼
                  git name-rev ────────────────────▶ version (成功時)
                        │ (失敗)
                        ▼
                  "<detached>" ────────────────────▶ version
                        │
                        ▼
                  git rev-parse --short ───────────▶ commit
                        │
                        ▼
                  printf ──────────────────────────▶ "version (commit)"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz versionコマンドの実装 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $ZSH変数の設定元 |
| .git | `$ZSH/.git` | ディレクトリ | gitリポジトリ情報 |
