# 画面設計書 13-Usage-Pre-commit

## 概要

本ドキュメントは、Prettierドキュメントサイトの「Usage - Pre-commit Hook」画面の設計書です。この画面はGitのpre-commitフックを使用してコミット前に自動的にPrettierを実行する方法を説明するドキュメントページです。

### 本画面の処理概要

この画面はGitのpre-commitフックとPrettierを連携させてステージングされたファイルを自動フォーマットするための各種方法を提供する静的ドキュメントページです。lint-staged、pretty-quick、Husky.Net、git-format-staged、シェルスクリプトの5つのオプションを詳細に解説しています。

**業務上の目的・背景**：チーム開発においてコードスタイルの一貫性を保つことは重要です。しかし、開発者が手動でPrettierを実行し忘れることがあります。pre-commitフックを設定することで、コミット時に自動的にフォーマットが適用され、未フォーマットのコードがリポジトリに入ることを防げます。この画面は、そうした自動化設定の具体的な手順を開発者に提供します。

**画面へのアクセス方法**：ユーザーはメインサイトのナビゲーションバーから「Docs」セクションに入り、サイドバーの「Usage」カテゴリ内の「Pre-commit」リンクをクリックしてアクセスします。URLは `/docs/precommit` です。

**主要な操作・処理内容**：
1. lint-stagedを使用したpre-commitフックの設定方法の理解
2. pretty-quickを使用した設定方法の理解
3. Husky.Netを使用した.NET環境での設定方法の理解
4. git-format-stagedを使用した部分ステージング対応の設定方法の理解
5. シェルスクリプトによる手動設定方法の理解

**画面遷移**：この画面からは外部のGitHubリポジトリ（lint-staged, husky, pretty-quick等）へのリンクが設定されています。

**権限による表示制御**：なし。全ユーザーが同一のコンテンツを閲覧可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ファイルフォーマット（--write） | 主機能 | pre-commitフックでのフォーマット実行方法を説明 |
| 18 | フォーマットチェック（--check） | 補助機能 | pre-commitフックでのチェックモードを説明 |

## 画面種別

ドキュメント / 参照

## URL/ルーティング

- **URL**: `/docs/precommit`
- **ソースファイル**: `docs/precommit.md`
- **生成方式**: Docusaurus docs機能によるMarkdownからの静的HTML生成

## 入出力項目

本画面は静的ドキュメントページのため、ユーザー入力フィールドはありません。

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| Option 1 | lint-staged | ESLint等と併用時、部分ステージング対応の推奨オプション |
| Option 2 | pretty-quick | ファイル全体フォーマットのシンプルなオプション |
| Option 3 | Husky.Net | .NET開発環境向けのオプション |
| Option 4 | git-format-staged | 部分ステージング対応の高度なオプション |
| Option 5 | Shell script | 手動でのシェルスクリプト設定方法 |
| パッケージマネージャータブ | npm/yarn/pnpm/bun | 各パッケージマネージャー向けのコマンド |

## イベント仕様

### 1-タブ切り替え

Docusaurusの`<Tabs>`コンポーネントにより、パッケージマネージャー（npm/yarn/pnpm/bun）別のコマンド表示を切り替えます。

### 2-外部リンククリック

ドキュメント内の外部リンクをクリックすると、対応するGitHubリポジトリに遷移します。

- lint-staged → GitHub: okonet/lint-staged
- husky → GitHub: typicode/husky
- pretty-quick → GitHub: prettier/pretty-quick
- simple-git-hooks → GitHub: toplenboren/simple-git-hooks
- Husky.Net → GitHub: alirezanet/Husky.Net
- git-format-staged → GitHub: hallettj/git-format-staged

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

本画面は静的ドキュメントページのため、データベース更新は発生しません。

## メッセージ仕様

本画面は静的ドキュメントページのため、動的メッセージはありません。

## 例外処理

| 状態 | 説明 |
|------|------|
| ページ未発見（404） | URLが誤っている場合、Docusaurus標準の404ページを表示 |
| 外部リンク切れ | 外部リポジトリのURLが変更された場合、ユーザーに404表示 |

## 備考

- 本ドキュメントはDocusaurusの`@theme/Tabs`と`@theme/TabItem`コンポーネントを使用してパッケージマネージャー別の表示を実現
- 各オプションのUse Caseが明記されており、状況に応じた選択が可能
- git-format-stagedはPython v3またはv2.7が必要と記載
- シェルスクリプト方式ではpost-commitフックの設定も案内

---

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

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

### 推奨読解順序

#### Step 1: ドキュメントコンテンツを理解する

本画面のコンテンツはMarkdownファイルで管理されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | precommit.md | `docs/precommit.md` | 5つのpre-commit設定オプションを理解 |

**読解のコツ**: Docusaurusの`import Tabs from "@theme/Tabs"`でタブコンポーネントをインポートし、パッケージマネージャー別のコマンドを表示しています。

#### Step 2: CLI --writeオプションの実装を理解する

pre-commitフックで使用される`--write`オプションの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/cli/index.js` | CLIエントリーポイント |
| 2-2 | format.js | `src/cli/format.js` | formatFiles関数でのファイル書き込み処理 |

**主要処理フロー**:
1. **111-113行目**: hasFilePatternsがtrueの場合formatFiles呼び出し
2. format.js内でwriteオプションに応じたファイル上書き処理

#### Step 3: --checkオプションの実装を理解する

pre-commitフックで使用される`--check`オプションの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/cli/index.js` | checkとlistDifferentの排他チェック |
| 3-2 | format.js | `src/cli/format.js` | checkモードでの差分検出処理 |

**主要処理フロー**:
- **49-51行目**: --checkと--list-differentの排他チェック

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

```
Git pre-commit hook
    │
    ├─ lint-staged / pretty-quick / etc.
    │      └─ prettier --write [staged files]
    │
    └─ prettier CLI
           │
           ├─ expand-patterns (ファイル展開)
           │
           └─ formatFiles()
                  ├─ format() - 各ファイルをフォーマット
                  └─ write() - ファイルを上書き
```

### データフロー図

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

git add (ステージング)
     │
     ▼
pre-commit hook ────────▶ lint-staged/pretty-quick
     │                          │
     │                          ▼
     │                    prettier --write
     │                          │
     │                          ▼
     │                    formatFiles()
     │                          │
     │                          ▼
ステージファイル ─────────▶ format() ─────────────▶ フォーマット済みファイル
                                                        │
                                                        ▼
                                                   git add (再ステージング)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| precommit.md | `docs/precommit.md` | ドキュメント | pre-commit設定ガイド |
| index.js | `src/cli/index.js` | ソース | CLIエントリーポイント |
| format.js | `src/cli/format.js` | ソース | フォーマット処理実装 |
| expand-patterns.js | `src/cli/expand-patterns.js` | ソース | ファイルパターン展開 |
