# 画面設計書 19-upgrade.sh

## 概要

本ドキュメントは、Oh My Zshを最新版にアップグレードするスクリプト `upgrade.sh` の画面設計書です。

### 本画面の処理概要

`upgrade.sh` は、Oh My Zshを最新版にアップグレードするための内部スクリプトです。`omz update` コマンドや自動更新機能から呼び出されます。

**業務上の目的・背景**：Oh My Zshは継続的に開発されており、新機能、バグ修正、セキュリティパッチが定期的にリリースされます。本スクリプトは、git pull --rebaseを使用してローカルリポジトリを最新状態に更新し、変更内容をユーザーに分かりやすく表示します。対話モードと非対話モード（silent/minimal）をサポートし、自動更新やCI/CD環境にも対応します。

**画面へのアクセス方法**：通常は `omz update` コマンドまたは自動更新機能から呼び出されます。直接実行する場合は `zsh $ZSH/tools/upgrade.sh [-i] [-v default|minimal|silent]` を実行します。

**主要な操作・処理内容**：
1. オプション解析（-v: 詳細モード、-i: 対話モード）
2. 古いリモートURLの更新（robbyrussell → ohmyzsh）
3. git設定の調整（eol, autocrlf, autoStash等）
4. 現在のブランチとHEADを記録
5. git pull --rebase でリポジトリを更新
6. 更新結果に応じてメッセージを表示
7. チェンジログを表示（対話モード時）
8. 元のブランチに戻る
9. git設定の復元

**画面遷移**：
- 遷移元: omz update コマンド、check_for_upgrade.sh からの呼び出し
- 遷移先: なし（呼び出し元に制御を戻す）

**権限による表示制御**：特になし。$ZSHディレクトリへの書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 79 | upgrade.sh | 主機能 | OMZリポジトリをgit pull --rebaseで更新し、チェンジログを表示 |

## 画面種別

シェルスクリプト（内部スクリプト）

## URL/ルーティング

```bash
# 直接実行（通常は非推奨）
zsh $ZSH/tools/upgrade.sh [-i] [-v default|minimal|silent]

# omz update経由（推奨）
omz update

# 環境変数を指定して実行
ZSH="$ZSH" zsh -f "$ZSH/tools/upgrade.sh" -i -v default
```

### コマンドライン引数

| 引数 | 説明 |
|------|------|
| -i | 対話モード（チェンジログを表示） |
| -v default | デフォルト詳細モード（バナー、SNSリンク表示） |
| -v minimal | 最小詳細モード（メッセージのみ） |
| -v silent | サイレントモード（エラーのみ） |

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | デフォルト | 説明 |
|--------|-----|------|----------|------|
| -i | フラグ | 任意 | false | 対話モードを有効化 |
| -v | 文字列 | 任意 | default | 詳細モード（default/minimal/silent） |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 更新状況 | テキスト | 更新処理の進捗 |
| 成功バナー | ASCII Art | Oh My Zshのレインボーロゴ |
| チェンジログ | テキスト | 更新内容の変更履歴 |
| SNSリンク | テキスト | X、Discord、ショップへのリンク |

## 表示項目

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

## イベント仕様

### 1-オプション解析

コマンドライン引数を解析します。

- getopts で -v と -i オプションを処理
- -v: default、minimal、silentを受け付け、無効な値は警告
- -i: interactiveフラグをtrueに設定

### 2-色設定初期化

ターミナルの色設定を初期化します。

- is_tty関数でTTY判定
- supports_truecolor関数でTrueColor対応判定
- RAINBOW配列に色コードを設定
- RED, GREEN, YELLOW, BLUE, BOLD, RESET変数を設定

### 3-リモートURL更新

古いリモートURLを新しいものに更新します。

- git remote -v で全リモートを確認
- robbyrussell/oh-my-zshを検出したらohmyzsh/ohmyzshに更新
- git://からhttps://への更新も実施
- oh-my-zsh.remoteにリモート名を保存

### 4-git設定

更新処理に必要なgit設定を行います。

- core.eol: lf
- core.autocrlf: false
- fsck.zeroPaddedFilemode: ignore
- fetch.fsck.zeroPaddedFilemode: ignore
- receive.fsck.zeroPaddedFilemode: ignore
- rebase.autoStash: true（元の設定をバックアップ）

### 5-リポジトリ状態取得

更新前の状態を記録します。

- remote変数: oh-my-zsh.remoteまたはorigin
- branch変数: oh-my-zsh.branchまたはmaster
- last_head: 現在のHEADまたはブランチ名
- last_commit: 更新前のコミットハッシュ

### 6-git pull実行

リポジトリを更新します。

- git checkout でupdateブランチに切り替え
- LANG= git pull --quiet --rebase $remote $branch を実行
- 成功時: HEADの変更を確認して適切なメッセージを表示
- 失敗時: エラーメッセージを表示

### 7-チェンジログ表示

更新内容を表示します（対話モード・デフォルトモード時）。

- oh-my-zsh.lastVersionに更新前コミットを保存
- changelog.shを呼び出して変更内容を表示

### 8-バナー・メッセージ表示

更新結果を表示します。

- defaultモード: レインボーバナー、メッセージ、SNSリンク
- minimalモード: メッセージのみ
- silentモード: 表示なし（エラー時のみ）

### 9-クリーンアップ

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

- git checkout で元のブランチに戻る
- rebase.autoStash設定を復元

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

本スクリプトはデータベースを使用しません。

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

| 操作 | 対象 | 操作種別 | 概要 |
|------|------|---------|------|
| git pull | $ZSH | UPDATE | リポジトリを最新版に更新 |
| git config | $ZSH/.git/config | UPDATE | リモートURL、各種設定を更新 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 情報 | "Updating Oh My Zsh" | 更新開始時（default/minimal） |
| 情報 | "Oh My Zsh is already at the latest version." | 更新なし時 |
| 情報 | "Hooray! Oh My Zsh has been updated!" | 更新あり時 |
| 情報 | "You can see the changelog with `omz changelog`" | 更新あり時（default/minimal） |
| エラー | "There was an error updating. Try again later?" | git pull失敗時 |
| 警告 | "[oh-my-zsh] update verbosity 'X' is not valid" | 無効な-v引数時 |

## 例外処理

| 例外状態 | 処理内容 |
|----------|----------|
| zsh以外から実行 | exec zshで再実行 |
| sourceで実行 | エラーメッセージを表示 |
| $ZSH未設定 | スクリプトの場所から自動設定 |
| 無効な-v引数 | 警告を表示、デフォルトを使用 |
| git pull失敗 | エラーメッセージを表示、非ゼロ終了 |
| git checkout失敗 | 終了コード1で終了 |

## 備考

- このスクリプトはzsh専用です（sh/bashでは動作しません）
- set +u で未定義変数チェックを無効化しています
- sourceで実行した場合は適切なエラーを返します
- 古いrobbyrussell URLは自動的にohmyzshに更新されます
- rebase.autoStashは一時的に有効化され、終了時に復元されます

---

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

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

### 推奨読解順序

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

まず、アップグレードスクリプトで使用される主要な変数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | upgrade.sh | `tools/upgrade.sh` 行23-24 | verbose_mode、interactive変数 |
| 1-2 | upgrade.sh | `tools/upgrade.sh` 行160-192 | RAINBOW、色変数の設定 |
| 1-3 | upgrade.sh | `tools/upgrade.sh` 行230-239 | remote、branch、last_head、last_commit変数 |

**読解のコツ**: zsh特有の構文（${...:-default}等）を理解してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | upgrade.sh | `tools/upgrade.sh` 行1-19 | スクリプト冒頭の保護処理 |
| 2-2 | upgrade.sh | `tools/upgrade.sh` 行26-38 | getopts によるオプション解析 |

**主要処理フロー**:
- **行7-9**: zsh以外からの実行を検出してzshで再実行
- **行12-14**: sourceでの実行をエラーとする
- **行17-19**: $ZSH未設定時の自動設定
- **行21**: $ZSHへ移動
- **行26-38**: -v、-iオプションの解析

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | upgrade.sh | `tools/upgrade.sh` 行194-214 | リモートURL更新処理 |
| 3-2 | upgrade.sh | `tools/upgrade.sh` 行216-226 | git設定処理 |
| 3-3 | upgrade.sh | `tools/upgrade.sh` 行241-283 | git pull処理と結果表示 |

**リモートURL更新の処理フロー**:
- **行195-214**: git remote -vでリモートを確認、robbyrussellをohmyzshに更新

**git設定の処理フロー**:
- **行218-223**: eol、autocrlf、fsck設定
- **行225-226**: autoStashの設定とバックアップ

**git pull処理の処理フロー**:
- **行242-244**: verbose_mode != silentなら開始メッセージ
- **行245-263**: git pull --rebaseと結果判定
- **行265-279**: バナーとメッセージ表示

#### Step 4: クリーンアップ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | upgrade.sh | `tools/upgrade.sh` 行285-295 | クリーンアップ処理 |

**クリーンアップの処理フロー**:
- **行286**: 元のブランチにcheckout
- **行289-292**: autoStash設定の復元
- **行295**: 終了コードを返す

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

```
zsh upgrade.sh [-i] [-v mode]
    │
    ├─ 保護処理 [tools/upgrade.sh:1-19]
    │      ├─ zsh以外からの実行チェック
    │      ├─ sourceでの実行チェック
    │      └─ $ZSH自動設定
    │
    ├─ オプション解析 [tools/upgrade.sh:26-38]
    │      └─ getopts -v -i
    │
    ├─ 色設定 [tools/upgrade.sh:160-192]
    │      ├─ is_tty
    │      └─ supports_truecolor
    │
    ├─ リモートURL更新 [tools/upgrade.sh:194-214]
    │      ├─ git remote -v
    │      └─ git remote set-url
    │
    ├─ git設定 [tools/upgrade.sh:216-226]
    │      └─ git config (複数)
    │
    ├─ リポジトリ状態取得 [tools/upgrade.sh:230-239]
    │      ├─ git config oh-my-zsh.remote/branch
    │      └─ git rev-parse
    │
    ├─ git pull [tools/upgrade.sh:241-283]
    │      ├─ git checkout
    │      ├─ git pull --quiet --rebase
    │      ├─ changelog.sh (対話モード時)
    │      └─ バナー・メッセージ表示
    │
    └─ クリーンアップ [tools/upgrade.sh:285-295]
           ├─ git checkout (元のブランチ)
           └─ git config (autoStash復元)
```

### データフロー図

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

-v mode ─────────────▶ オプション解析
-i                          │
                           ▼
                     リモートURL更新 ──────────────────▶ git config更新
                           │
                           ▼
                     git設定 ──────────────────────────▶ git config更新
                           │
                           ▼
                     状態取得 ─────────────────────────▶ last_commit保存
                           │
                           ▼
                     git pull --rebase ────────────────▶ リポジトリ更新
                           │
                           ▼
                     結果判定
                           │
                     ┌─────┴─────┐
                     ▼           ▼
                更新あり      更新なし
                     │           │
                     ▼           ▼
             チェンジログ    "already at latest"
             バナー表示
                     │
                     └─────┬─────┘
                           ▼
                     クリーンアップ ────────────────────▶ 設定復元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| upgrade.sh | `tools/upgrade.sh` | ソース | メインアップグレードスクリプト |
| changelog.sh | `tools/changelog.sh` | ソース | チェンジログ表示 |
| cli.zsh | `lib/cli.zsh` | ソース | omz updateコマンド（呼び出し元） |
| check_for_upgrade.sh | `tools/check_for_upgrade.sh` | ソース | 自動更新チェック（呼び出し元） |
| .git/config | `$ZSH/.git/config` | 設定 | gitリポジトリ設定 |
