# 画面設計書 13-omz update

## 概要

本ドキュメントは、Oh My Zshを最新版に更新するCLIコマンド `omz update` の画面設計書です。

### 本画面の処理概要

`omz update` コマンドは、Oh My Zshフレームワークを最新版にアップデートするためのコマンドインターフェースです。

**業務上の目的・背景**：Oh My Zshは活発に開発されており、新しいプラグイン、テーマ、バグ修正、セキュリティパッチが定期的にリリースされます。ユーザーがこれらの最新機能を利用し、セキュリティを維持するためには、定期的な更新が必要です。本コマンドは、対話的な更新プロセスを提供し、更新内容をユーザーに分かりやすく表示します。

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

**主要な操作・処理内容**：
1. gitコマンドの存在確認
2. $ZSHがgitリポジトリであることを確認
3. 現在のHEADコミットを記録
4. upgrade.shスクリプトを実行して更新を実施
5. .zsh-updateファイルを更新して最終更新日を記録
6. 更新ロックファイルを削除
7. 変更があった場合、zshセッションを再起動

**画面遷移**：
- 遷移元: omzコマンドのサブコマンドとして呼び出し
- 遷移先: 更新成功後、zshセッションが自動的に再起動される

**権限による表示制御**：特になし。ただし、$ZSHディレクトリへの書き込み権限とgitコマンドの実行権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてアップデートを実行 |
| 7 | omz update | 主機能 | OMZリポジトリをリモートからgit pullで更新し、チェンジログを表示 |
| 79 | upgrade.sh | 補助機能 | tools/upgrade.shを実行して実際の更新処理を行う |

## 画面種別

コマンドラインインターフェース

## URL/ルーティング

```
omz update
```

引数は不要です。

## 入出力項目

### 入力項目

なし（自動実行）

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 更新状況 | テキスト | 更新処理の進捗と結果 |
| チェンジログ | テキスト | 更新内容の変更履歴（対話モード時） |
| 成功バナー | ASCII Art | Oh My Zshロゴと成功メッセージ |

## 表示項目

| 表示項目 | 表示条件 | 説明 |
|----------|----------|------|
| 更新中メッセージ | 常時 | "Updating Oh My Zsh" |
| 更新成功メッセージ | 更新あり | "Hooray! Oh My Zsh has been updated!" |
| 最新版メッセージ | 更新なし | "Oh My Zsh is already at the latest version." |
| チェンジログ案内 | 更新あり | "You can see the changelog with `omz changelog`" |
| Oh My Zshバナー | defaultモード | レインボーカラーのASCIIアートロゴ |
| SNS案内 | defaultモード | X(Twitter)、Discord、ショップへのリンク |
| エラーメッセージ | エラー時 | "There was an error updating. Try again later?" |

## イベント仕様

### 1-前提条件確認

更新処理を開始する前の条件確認を行います。

- gitコマンドの存在を確認
- --unattendedフラグが渡された場合はエラー（非推奨）
- $ZSHがgitリポジトリであることを確認
- 現在のHEADコミットを記録

### 2-upgrade.sh実行

実際の更新処理をupgrade.shスクリプトに委譲します。

- zstyle ':omz:update' verboseから詳細モード設定を取得
- 詳細モード: default（デフォルト）、minimal、silent
- `zsh -f "$ZSH/tools/upgrade.sh" -i -v $verbose_mode` を実行

### 3-更新完了後処理

更新完了後の後処理を行います。

- .zsh-updateファイルにLAST_EPOCH（日数）を書き込み
- update.lockディレクトリを削除
- HEADが変更されていれば、zshセッションを再起動

### 4-セッション再起動

更新後のzshセッション再起動を行います。

- ZSH_ARGZEROまたはfunctraceから実行中のzshパスを取得
- ログインシェルかどうかを判定
- exec -l または exec でzshを再起動

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

本コマンドはデータベースを使用しません。ファイルシステムとgitリポジトリの操作を行います。

### 操作別ファイルシステム影響一覧

| 操作 | 対象 | 操作種別 | 概要 |
|------|------|---------|------|
| git pull | $ZSH | UPDATE | リポジトリを最新版に更新 |
| .zsh-update更新 | $ZSH_CACHE_DIR/.zsh-update | UPDATE | 最終更新日を記録 |
| update.lock削除 | $ZSH/log/update.lock | DELETE | 更新ロックを解除 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| エラー | "git is not installed. Aborting..." | gitなし時 |
| エラー | "the `--unattended` flag is no longer supported..." | --unattended使用時 |
| エラー | "`$ZSH` is not a git directory. Aborting..." | gitリポジトリでない時 |
| 情報 | "Updating Oh My Zsh" | 更新開始時 |
| 情報 | "Oh My Zsh is already at the latest version." | 更新なし時 |
| 情報 | "Hooray! Oh My Zsh has been updated!" | 更新あり時 |
| 情報 | "You can see the changelog with `omz changelog`" | 更新あり時 |
| エラー | "There was an error updating. Try again later?" | 更新失敗時 |

## 例外処理

| 例外状態 | 処理内容 |
|----------|----------|
| gitコマンドなし | エラーメッセージを表示して終了 |
| --unattended使用 | 非推奨警告とFAQリンクを表示して終了 |
| gitリポジトリでない | エラーメッセージを表示して終了 |
| upgrade.sh失敗 | エラーコードを返して終了（セッション再起動なし） |
| git pull失敗 | エラーメッセージを表示して終了 |

## 備考

- `--unattended`フラグは廃止され、代わりにupgrade.shを直接使用することが推奨されています
- 詳細モードはzstyle ':omz:update' verboseで設定可能（default、minimal、silent）
- 更新があった場合のみzshセッションが再起動されます
- upgrade.shは内部的にgit pull --rebaseを使用します

---

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

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

### 推奨読解順序

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

まず、更新処理で使用される主要な変数とファイルを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | _omz::update関数内のローカル変数（last_commit, verbose_mode等） |
| 1-2 | .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | LAST_EPOCH変数の形式を理解 |

**読解のコツ**: zmodload zsh/datetimeとEPOCHSECONDSによるエポック秒の取り扱いを理解してください。

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

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

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

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

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

**主要処理フロー**:
- **行887-890**: gitコマンドの存在確認
- **行892-897**: --unattendedフラグの非推奨警告
- **行899-903**: 現在のHEADを取得、gitリポジトリ確認
- **行906-907**: verbose_mode取得とupgrade.sh実行
- **行909-913**: .zsh-updateファイル更新とロック削除
- **行915-921**: HEAD変更時のセッション再起動

#### Step 4: upgrade.shの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | upgrade.sh | `tools/upgrade.sh` | 実際のgit pull処理とチェンジログ表示 |

**主要処理フロー**:
- **行1-38**: オプション解析（-v, -i）
- **行40-192**: 色設定とターミナルサポート検出
- **行194-214**: リモートURL更新（旧robbyrussell → ohmyzsh）
- **行216-226**: git設定（eol, autocrlf, autoStash等）
- **行228-239**: リポジトリ状態取得
- **行241-283**: git pull --rebase実行と結果表示
- **行285-295**: クリーンアップ処理

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

```
omz update
    │
    ├─ omz [lib/cli.zsh:3-21]
    │      └─ _omz::update [lib/cli.zsh:885-922]
    │             │
    │             ├─ git rev-parse HEAD (現在コミット取得)
    │             │
    │             ├─ zsh -f "$ZSH/tools/upgrade.sh"
    │             │      └─ upgrade.sh [tools/upgrade.sh]
    │             │             ├─ git remote set-url (URL更新)
    │             │             ├─ git config (設定変更)
    │             │             ├─ git pull --rebase (更新)
    │             │             └─ changelog.sh (変更履歴表示)
    │             │
    │             ├─ echo LAST_EPOCH > .zsh-update
    │             ├─ rm -rf update.lock
    │             │
    │             └─ exec zsh (セッション再起動)
    │
    └─ _omz [lib/cli.zsh:23-112] (補完関数)
```

### データフロー図

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

(なし) ─────────▶ git rev-parse HEAD ────────────────▶ last_commit保存
                        │
                        ▼
                  upgrade.sh実行 ─────────────────────▶ 更新状況表示
                        │                              チェンジログ表示
                        ▼                              バナー表示
                  .zsh-update更新 ────────────────────▶ LAST_EPOCH保存
                        │
                        ▼
                  update.lock削除
                        │
                        ▼ (HEAD変更あり)
                  exec zsh ───────────────────────────▶ セッション再起動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz updateコマンドの実装 |
| upgrade.sh | `tools/upgrade.sh` | ソース | 実際のgit pull処理 |
| changelog.sh | `tools/changelog.sh` | ソース | 変更履歴の生成・表示 |
| .zsh-update | `$ZSH_CACHE_DIR/.zsh-update` | 設定 | 最終更新日の記録 |
| update.lock | `$ZSH/log/update.lock` | ロック | 更新処理の排他制御 |
