# 機能設計書 7-omz update

## 概要

本ドキュメントは、Oh My Zsh（以下OMZ）の更新機能「omz update」コマンドに関する機能設計書である。OMZリポジトリをリモートからgit pullで更新し、チェンジログを表示する処理について記述する。

### 本機能の処理概要

本機能は、OMZのGitリポジトリを最新状態に更新し、更新内容をユーザーに通知する。対話モードでの手動更新と、自動更新チェックからの呼び出しの両方に対応。

**業務上の目的・背景**：OMZは活発に開発が行われており、バグ修正、新機能追加、セキュリティパッチが頻繁にリリースされる。ユーザーが簡単に最新版に更新できる仕組みが必要である。また、更新内容を確認できるようチェンジログ表示機能も提供。

**機能の利用シーン**：
- ユーザーが`omz update`コマンドを実行した時
- 自動更新チェックで更新が検出され、ユーザーが承認した時
- 自動更新モード（auto）で更新が実行される時

**主要な処理内容**：
1. Gitコマンドの利用可能性確認
2. 現在のHEADコミット取得
3. tools/upgrade.shの実行
4. 更新後のHEAD確認
5. 変更があった場合はシェルリロード

**関連システム・外部連携**：Git（リポジトリ更新）、GitHub（リモートリポジトリ）

**権限による制御**：$ZSHディレクトリへの書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 13 | omz update | 主機能 | アップデートを実行 |

## 機能種別

CLI / 更新処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| verbose | zstyle設定 | No | 更新時の表示レベル（default/minimal/silent） | :omz:update verbose |

### 入力データソース

- $ZSH/.gitリポジトリ
- GitHub ohmyzsh/ohmyzshリモートリポジトリ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| stdout | テキスト | 更新結果、チェンジログ |
| 戻り値 | 整数 | 0: 成功、非0: エラー |

### 出力先

- 標準出力（更新結果、チェンジログ）
- $ZSH_CACHE_DIR/.zsh-update（最終更新日時）

## 処理フロー

### 処理シーケンス

```
1. Gitコマンド確認
   └─ git コマンドが利用可能か確認
   └─ 利用不可の場合はエラー終了

2. --unattendedフラグチェック
   └─ 非推奨フラグが使用された場合はエラー終了

3. 現在のHEAD取得
   └─ git rev-parse HEADで現在のコミットハッシュを取得
   └─ 取得失敗の場合はエラー終了

4. upgrade.sh実行
   └─ zstyleからverbose設定を取得
   └─ tools/upgrade.shを-iと-v オプション付きで実行

5. 更新日時記録
   └─ $ZSH_CACHE_DIR/.zsh-updateに LAST_EPOCH を記録

6. 更新ロック削除
   └─ $ZSH/log/update.lockを削除

7. シェルリロード判定
   └─ 更新前後のHEADを比較
   └─ 異なる場合はシェルをexecで再起動
```

### フローチャート

```mermaid
flowchart TD
    A[omz update実行] --> B{git利用可能?}
    B -->|No| C[エラー: git未インストール]
    B -->|Yes| D{--unattended使用?}
    D -->|Yes| E[エラー: 非推奨フラグ]
    D -->|No| F[現在のHEAD取得]
    F --> G{取得成功?}
    G -->|No| H[エラー: Gitリポジトリでない]
    G -->|Yes| I[verbose設定取得]
    I --> J[upgrade.sh実行]
    J --> K{更新成功?}
    K -->|No| L[エラー返却]
    K -->|Yes| M[更新日時記録]
    M --> N[update.lock削除]
    N --> O{HEAD変更あり?}
    O -->|Yes| P[シェルリロード]
    O -->|No| Q[完了]
    P --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Git必須 | gitコマンドが利用可能であること | 常時 |
| BR-02 | 非推奨フラグ拒否 | --unattendedフラグは非推奨でエラー | --unattended指定時 |
| BR-03 | verboseモード | default/minimal/silentの3モードをサポート | zstyle設定時 |
| BR-04 | 自動リロード | 更新によりHEADが変更された場合は自動リロード | 更新成功時 |
| BR-05 | 更新日時記録 | 更新成功時に最終更新日時を記録 | 更新成功時 |

### 計算ロジック

**LAST_EPOCH計算**:
```zsh
LAST_EPOCH=$(( EPOCHSECONDS / 60 / 60 / 24 ))
```
- EPOCHSECONDSを日単位に変換

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | Git未インストール | gitコマンドが利用不可 | エラーメッセージ出力 |
| 1 | 非推奨フラグ | --unattended使用 | FAQへの案内出力 |
| 1 | 非Gitディレクトリ | $ZSHがGitリポジトリでない | エラーメッセージ出力 |
| 非0 | 更新失敗 | git pull失敗等 | upgrade.shのエラーを返却 |

### リトライ仕様

リトライは行わない。ユーザーが再度コマンドを実行する。

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

本機能はトランザクションを使用しないが、upgrade.shでrebase.autoStash設定を一時的に変更し、処理後に復元する。

## パフォーマンス要件

- ネットワーク接続に依存するため、タイムアウトはGitのデフォルト設定に従う
- 更新処理中はユーザー入力をブロック

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

- git pull --rebaseで更新を実行
- リモートURLが正規のohmyzsh/ohmyzshリポジトリであることを確認

## 備考

- verbose設定はzstyle ':omz:update' verboseで制御
- チェンジログはtools/changelog.shで生成
- 更新後のシェルリロードはexecで現在のプロセスを置き換え

---

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

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

### 推奨読解順序

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

更新処理で扱う変数と設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | verbose_mode、last_commit等の変数 |

**読解のコツ**:
- zstyleで`:omz:update`のverbose設定を参照
- LAST_EPOCHは日単位のエポック値

#### Step 2: _omz::update関数を理解する

更新コマンドのエントリーポイントを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | 885-922行目の_omz::update関数 |

**主要処理フロー**:
- **887-890行目**: gitコマンド存在確認
- **893-897行目**: --unattendedフラグチェック
- **899-903行目**: 現在のHEAD取得
- **906-907行目**: verbose設定取得とupgrade.sh実行
- **910-913行目**: 更新日時記録とロック削除
- **916-920行目**: HEAD変更時のシェルリロード

#### Step 3: upgrade.shを理解する

実際の更新処理を行うスクリプトを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | upgrade.sh | `tools/upgrade.sh` | 全体の流れ |

**主要処理フロー**:
- **1-38行目**: 引数解析（-v, -i）
- **40-192行目**: ターミナル判定と色設定
- **194-213行目**: リモートURL更新（古いURLの修正）
- **216-226行目**: Git設定（eol, autocrlf, fsck等）
- **228-239行目**: リポジトリ状態取得
- **241-279行目**: git pull --rebase実行と結果表示
- **285-292行目**: 設定復元

#### Step 4: 表示モードを理解する

verbose設定による出力制御を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | upgrade.sh | `tools/upgrade.sh` | 265-279行目の表示制御 |

**主要処理フロー**:
- **default**: アスキーアート + メッセージ + リンク
- **minimal**: メッセージのみ
- **silent**: 出力なし

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

```
omz update
    │
    └─ _omz::update()
           │
           ├─ git rev-parse HEAD (更新前HEAD取得)
           │
           ├─ zstyle -s ':omz:update' verbose
           │
           ├─ tools/upgrade.sh -i -v $verbose_mode
           │      │
           │      ├─ git remote -v (リモート確認)
           │      │
           │      ├─ git config (設定変更)
           │      │
           │      ├─ git checkout $branch
           │      │
           │      ├─ git pull --quiet --rebase $remote $branch
           │      │
           │      ├─ tools/changelog.sh (チェンジログ表示)
           │      │
           │      └─ git checkout $last_head (元に戻る)
           │
           ├─ echo "LAST_EPOCH=..." > .zsh-update
           │
           ├─ rm -rf update.lock
           │
           └─ exec $zsh (HEAD変更時)
```

### データフロー図

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

omz update            ───▶ _omz::update()
                              │
                              ├─▶ HEAD取得 ────────────────▶ last_commit変数
                              │
GitHub (remote)       ───▶ git pull --rebase ──────────▶ 更新されたファイル群
                              │
                              ├─▶ changelog.sh ────────────▶ チェンジログ表示
                              │
                              └─▶ LAST_EPOCH記録 ──────────▶ .zsh-update
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | _omz::update関数 |
| upgrade.sh | `tools/upgrade.sh` | ソース | 実際の更新処理 |
| changelog.sh | `tools/changelog.sh` | ソース | チェンジログ生成 |
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | データ | 最終更新日時記録 |
| update.lock | `$ZSH/log/update.lock` | ロック | 更新排他制御 |
