# 画面設計書 12-omz pr clean

## 概要

本ドキュメントは、Oh My ZshのPull Requestテスト用に作成されたブランチを一括削除するCLIコマンド `omz pr clean` の画面設計書です。

### 本画面の処理概要

`omz pr clean` コマンドは、`omz pr test` コマンドによって作成されたテスト用PRブランチ（`ohmyzsh/pull-*`）を一括削除するためのコマンドインターフェースです。

**業務上の目的・背景**：PRテストを繰り返し実行すると、ローカルリポジトリに多数の `ohmyzsh/pull-*` ブランチが蓄積されます。これらのブランチはテスト完了後は不要となりますが、手動で一つずつ削除するのは煩雑です。本コマンドは、これらのテスト用ブランチを一覧表示し、ユーザーの確認を得た上で一括削除することで、リポジトリの整理を効率化します。

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

**主要な操作・処理内容**：
1. $ZSHディレクトリに移動
2. `ohmyzsh/pull-*` パターンに一致するブランチを検索
3. 見つかったブランチを色付きで一覧表示
4. ユーザーに削除確認を求める
5. 確認後、全てのPRブランチを削除

**画面遷移**：
- 遷移元: `omz pr` コマンドのサブコマンドとして呼び出し
- 遷移先: なし（処理完了後、通常のシェルプロンプトに戻る）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてPRブランチ削除を実行 |
| 20 | omz pr clean | 主機能 | ohmyzsh/pull-*ブランチをすべて削除 |

## 画面種別

コマンドラインインターフェース（対話型）

## URL/ルーティング

```
omz pr clean
```

引数は不要です。

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| 確認応答 | 文字 | 必須 | Y/y/Enterで削除実行、それ以外でキャンセル |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ブランチ一覧 | テキスト | 削除対象のPRブランチを色付きで表示 |
| 確認プロンプト | テキスト | 削除確認のプロンプト |
| 処理結果 | テキスト | 削除処理の結果メッセージ |

## 表示項目

| 表示項目 | 表示条件 | 説明 |
|----------|----------|------|
| PRブランチなしメッセージ | ブランチなし時 | "there are no Pull Request branches to remove." |
| ブランチ一覧 | ブランチあり時 | ブランチ名、コミットハッシュ、コミットメッセージを色付きで表示 |
| 確認プロンプト | ブランチあり時 | "do you want remove these Pull Request branches? [Y/n]" |
| 削除中メッセージ | 確認後 | "removing all Oh My Zsh Pull Request branches..." |
| 各ブランチの削除結果 | 削除実行時 | git branch -Dの出力 |

## イベント仕様

### 1-PRブランチ検索

$ZSHディレクトリ内でPRブランチを検索します。

- サブシェル内で処理を実行（set -eでエラー時に即座に終了）
- `git for-each-ref` でブランチ情報を取得
- フォーマット: ブランチ名（青色太字右寄せ）、コミットハッシュ（赤色薄字）、コミットメッセージ（黄色）
- パターン: `refs/heads/ohmyzsh/pull-*`

### 2-削除確認

ブランチが見つかった場合、削除の確認を行います。

- `_omz::confirm` 関数で確認プロンプトを表示
- Y/y/Enterの場合のみ削除を実行
- それ以外の入力は処理をキャンセル

### 3-ブランチ削除

確認後、全てのPRブランチを削除します。

- `git branch --list 'ohmyzsh/pull-*'` で対象ブランチを取得
- 各ブランチに対して `git branch -D` を実行（強制削除）
- 削除結果をリアルタイムで表示

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

本コマンドはデータベースを使用しません。gitリポジトリの操作のみを行います。

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

| 操作 | 対象 | 操作種別 | 概要 |
|------|------|---------|------|
| ブランチ削除 | $ZSH/.git/refs/heads/ohmyzsh/pull-* | DELETE | PRテスト用ブランチを削除 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 情報 | "there are no Pull Request branches to remove." | PRブランチなし時 |
| プロンプト | "do you want remove these Pull Request branches? [Y/n]" | PRブランチあり時 |
| 情報 | "removing all Oh My Zsh Pull Request branches..." | 削除実行時 |
| 情報 | "Deleted branch ohmyzsh/pull-X (was XXXXXXX)." | 各ブランチ削除時（git出力） |

## 例外処理

| 例外状態 | 処理内容 |
|----------|----------|
| PRブランチなし | 情報メッセージを表示して正常終了 |
| 削除キャンセル | 処理を中断して終了（メッセージなし） |
| git操作エラー | set -eによりサブシェルが終了 |

## 備考

- `git branch -D` は強制削除オプションであり、マージされていない変更も削除されます
- 削除前に必ずブランチ一覧が表示されるため、意図しない削除を防げます
- 削除対象は `ohmyzsh/pull-*` パターンに一致するブランチのみです

---

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

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

### 推奨読解順序

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

まず、コマンドで使用される主要な変数を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | `_omz::pr::clean`関数内のローカル変数（fmt, branches）を確認 |

**読解のコツ**: git for-each-refのフォーマット文字列の理解が重要です。ANSIカラーコードを使用しています。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | omz関数（3-21行目）がエントリーポイント |
| 2-2 | cli.zsh | `lib/cli.zsh` | _omz::pr関数（541-559行目）がprサブコマンドのルーター |

**主要処理フロー**:
1. **行3-20**: omzコマンド → _omz::pr関数を呼び出し
2. **行541-558**: _omz::pr → _omz::pr::clean関数を呼び出し

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

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

**主要処理フロー**:
- **行562-564**: サブシェル開始、set -e、$ZSHへ移動
- **行566-569**: ブランチ表示フォーマット定義とブランチ検索
- **行571-575**: ブランチなし時の早期リターン
- **行577-582**: ブランチ一覧表示と確認プロンプト
- **行584-587**: ブランチ削除処理

#### Step 4: ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | `_omz::confirm`関数（121-135行目）- 確認プロンプト表示 |
| 4-2 | cli.zsh | `lib/cli.zsh` | `_omz::log`関数（137-162行目）- ログ出力 |

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

```
omz pr clean
    │
    ├─ omz [lib/cli.zsh:3-21]
    │      └─ _omz::pr [lib/cli.zsh:541-559]
    │             └─ _omz::pr::clean [lib/cli.zsh:561-589]
    │                    │
    │                    ├─ git for-each-ref (ブランチ検索)
    │                    ├─ _omz::log [lib/cli.zsh:137-162]
    │                    ├─ _omz::confirm [lib/cli.zsh:121-135]
    │                    ├─ git branch --list (ブランチ一覧取得)
    │                    └─ git branch -D (ブランチ削除)
    │
    └─ _omz [lib/cli.zsh:23-112] (補完関数)
```

### データフロー図

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

(なし) ─────────▶ git for-each-ref ──────────────────▶ ブランチ一覧表示
                        │
                        ▼ (ブランチあり)
                  _omz::confirm ─────────────────────▶ 確認プロンプト
                        │
                        ▼ (Y/y/Enter)
                  git branch -D (ループ) ────────────▶ 削除結果表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドおよびpr cleanサブコマンドの実装 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | Oh My Zshのメイン初期化スクリプト（cli.zshをsource） |
