> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ブランチとマージ

> Diversion におけるブランチとマージの動作について、ブランチの作成、ブランチ間の切り替え、マージ競合の解決方法を含めて学びます。

# ブランチとマージ

Diversion のブランチとマージにより、チームは安定したメインブランチを維持しながら、複数の機能を並行して作業できます。ミリ秒単位のブランチ作成とスマートマージにより、Diversion は並行開発を簡単にします。

## ブランチとは？

**ブランチ** は、リポジトリ内の独立した開発ラインです。ブランチを使用すると：

* メインコードベースに影響を与えずに機能に取り組む
* 変更を安全に試す
* 別々のタスクを同時に共同作業する
* 新機能を開発しながら安定したリリースバージョンを維持する

**Diversion における主な特徴：**

* リポジトリのサイズに関係なく、ブランチの作成はミリ秒単位
* ブランチはサーバーサイド（クラウドベース）
* すべてのチームメンバーがすべてのブランチを見ることができる
* ファイルのコピーや重複はなし

## ブランチとワークスペースの違い

ブランチについて詳しく学ぶ前に、ブランチがワークスペースとどのように関連しているかを理解することが重要です：

| 概念          | 目的           | 可視性         | 一般的な寿命      |
| ----------- | ------------ | ----------- | ----------- |
| **ブランチ**    | 独立した開発ライン    | すべてのチームメンバー | 数日〜数週間      |
| **ワークスペース** | あなたのローカル作業環境 | あなたのみ       | プロジェクト全体の期間 |

**こう考えてください：**

* **ブランチ** = コードが存在する場所（`main`、`feature-ui`、`bugfix-123` など）
* **ワークスペース** = 個人的な作業台（ファイルをローカルで編集する場所）

**ワークフローの例：**

```bash theme={null}
# あなたのワークスペースは 'main' ブランチを指している
dv checkout main

# 新しい機能ブランチを作成する
dv branch -c feature-ui

# ワークスペースを新しいブランチに切り替える
dv checkout feature-ui

# ワークスペースで変更を加える
# ... ファイルを編集 ...

# feature-ui ブランチにコミットする
dv commit -a -m "Add new UI components"
```

[ワークスペースについて詳しく →](/ja/concepts/repo-branch-workspace)

***

## ブランチを作成する

[デスクトップアプリでブランチを作成](/ja/basic/working-in-parallel#新しいブランチの作成) することもできます。

### 新しいブランチを作成する

現在の位置からブランチを作成します：

```bash theme={null}
dv branch -c feature-name
```

**何が起こるか：**

1. Diversion は現在のコミットを指す新しいブランチを作成します
2. ブランチはすぐにすべてのチームメンバーが利用できるようになります
3. 作成にはリポジトリサイズに関係なく約 100ms かかります

**例：**

```bash theme={null}
# 新機能のためのブランチを作成する
dv branch -c feature-new-level

# バグ修正のためのブランチを作成する
dv branch -c bugfix-character-movement
```

### 特定のコミットからブランチを作成する

```bash theme={null}
# まず、コミット ID を見つける
dv log

# コミットをチェックアウトする
dv checkout <commit-id>

# 新しいブランチを作成する
dv branch -c feature-name 
```

### すべてのブランチを一覧表示する

```bash theme={null}
dv branch
```

**出力例：**

```
* main
  feature-new-level
  bugfix-character-movement
  release-v1.0
```

`*` はワークスペースの現在のブランチを示します。

***

## ブランチ間の切り替え

[デスクトップアプリでブランチを切り替える](/ja/basic/working-in-parallel#ブランチの切り替え) こともできます。

### ブランチをチェックアウトする

ワークスペースを別のブランチに切り替えます：

```bash theme={null}
dv checkout feature-name
```

**何が起こるか：**

1. Diversion はワークスペースのファイルをターゲットブランチに合わせて更新します
2. ローカルファイルはブランチの状態を反映するように変更されます
3. 新しいコミットはこのブランチに対して行われます

**ワークフローの例：**

```bash theme={null}
# 現在どのブランチにいるか確認する
dv status

# メインブランチに切り替える
dv checkout main

# 機能ブランチに切り替える
dv checkout feature-new-level

# 変更を加えてコミットする
dv commit -a -m "Add level geometry"
```

<Warning>
  **ブランチを切り替える前に：**

  * 現在の変更をコミットする、破棄する、または [シェルブ](/ja/core-concepts/shelving) する
  * コミットされていない変更がある場合、Diversion が警告します
  * `dv status` を使用して保留中の変更を確認する
</Warning>

***

## ブランチをマージする

[デスクトップアプリでブランチをマージ](/ja/basic/working-in-parallel#マージの方法) することもできます。

マージは、あるブランチの変更を別のブランチに統合します。Diversion は自動的な競合検出を備えたスマートマージをサポートしています。

### 基本的なマージのワークフロー

**目標：** `feature-ui` を `main` にマージする

<Steps>
  <Step title="ターゲットブランチに切り替える">
    まず、マージ **先** のブランチをチェックアウトします：

    ```bash theme={null}
    dv checkout main
    ```
  </Step>

  <Step title="ソースブランチをマージする">
    機能ブランチを main にマージします：

    ```bash theme={null}
    dv merge feature-ui
    ```
  </Step>

  <Step title="競合を解決する（必要な場合）">
    競合がある場合、Diversion が解決を案内します：

    ```bash theme={null}
    # 競合を表示
    dv status

    # エディターで競合を解決した後
    dv commit -a -m "Merge feature-ui into main"
    ```
  </Step>

  <Step title="機能ブランチを削除する（オプション）">
    マージ後、機能ブランチを削除できます：

    ```bash theme={null}
    dv branch -d feature-ui
    ```
  </Step>
</Steps>

### マージの仕組み

Diversion は共通祖先の検出を伴う **3-way マージ** を使用します：

```
     A---B---C  (main)
          \
           D---E  (feature-ui)
```

**main から `dv merge feature-ui` を実行すると：**

1. Diversion は **共通祖先**（コミット B）を見つけます
2. B→C（main の変更）の変更を比較します
3. B→E（feature の変更）の変更を比較します
4. 両方の変更セットをインテリジェントに結合します
5. 新しいマージコミットを作成します：

```
     A---B---C---M  (main)
          \     /
           D---E  (feature-ui)
```

**メリット：**

* 両方のブランチの履歴を保持
* 競合を正確に検出
* 完全な監査証跡を維持

### マージ戦略

**通常のマージ（デフォルト）：**

* 両方のブランチのすべてのコミットを保持
* マージコミットを作成
* `dv log` で完全な履歴を確認可能

```bash theme={null}
dv merge feature-name
```

**マージするタイミング：**

* 完全な履歴が欲しい場合
* 機能のコミットが重要なマイルストーンである場合
* 誰がどの変更を行ったかを追跡する必要がある場合

***

## マージ競合の処理

デスクトップアプリは視覚的な競合解決ツールを提供します — [デスクトップアプリでのマージ競合](/ja/basic/working-in-parallel#マージ競合) を参照してください。

マージ競合は、同じ行のコードが両方のブランチで変更された場合に発生します。

### 競合検出

Diversion は競合が発生する前に防止します：

**リアルタイム通知：**

* 誰がどのファイルを編集しているか確認できる
* 作業中のファイルをチームメイトが変更したときに通知を受ける
* 競合が発生する前に変更を調整する

[競合防止について詳しく →](/ja/concepts/conflicts)

### 競合を解決する

競合が発生した場合、Diversion は簡単に解決できるようにします：

<Steps>
  <Step title="競合するファイルを特定する">
    ```bash theme={null}
    dv merge feature-ui
    # 出力: Conflict in src/player.cpp

    dv status
    # 表示: 競合するファイル
    ```
  </Step>

  <Step title="競合するファイルを開く">
    競合マーカーは両方のバージョンを表示します：

    ```cpp theme={null}
    <<<<<<< HEAD (main)
    int speed = 100;
    =======
    int speed = 150;
    >>>>>>> feature-ui
    ```
  </Step>

  <Step title="変更を選択または結合する">
    ファイルを編集して競合を解決します：

    ```cpp theme={null}
    // 片方を選択
    int speed = 150;

    // または結合する
    int speed = 125; // ブランチ間の妥協
    ```
  </Step>

  <Step title="解決済みとしてマークする">
    解決したマージをコミットします：

    ```bash theme={null}
    dv commit -a -m "Merge feature-ui: resolve speed conflict"
    ```
  </Step>
</Steps>

### 競合解決のオプション

**片方を完全に受け入れる：**

Web UI または API から：

* 「ours」を受け入れる（main のバージョンを保持）
* 「theirs」を受け入れる（機能ブランチのバージョンを使用）
* すべての競合を一度に受け入れる

**手動解決：**

* ファイルを編集して変更を結合する
* 満足したらコミットする

***

## ブランチのベストプラクティス

### 1. ブランチ命名規則

説明的で一貫した名前を使用します：

**良い例：**

```bash theme={null}
feature/new-character-controller
bugfix/inventory-crash
hotfix/v1.2-save-bug
release/v2.0
experimental/ai-pathfinding
```

**命名パターン：**

* `feature/` - 新機能
* `bugfix/` - バグ修正
* `hotfix/` - 緊急の本番修正
* `release/` - リリースブランチ
* `experimental/` - 実験的な作業

### 2. ブランチを短命に保つ

**理由：**

* マージ競合を減らす
* 変更のレビューが容易
* 迅速な統合

**方法：**

* 機能ブランチは週単位ではなく数日以内にマージする
* マージ後にブランチを削除する
* 小さく焦点を絞ったブランチを作成する

### 3. 頻繁にマージする

`main` を定期的に機能ブランチにマージします：

```bash theme={null}
# 機能ブランチで
dv checkout feature-ui
dv merge main

# これにより機能を main と最新の状態に保てる
```

**メリット：**

* 小さく容易なマージ
* 競合を早期に検出
* 機能が最新の main と互換性を保つ

### 4. 説明的なコミットメッセージを使う

```bash theme={null}
# 良い
dv commit -m "Add character jump animation"

# より良い
dv commit -m "Add character jump animation

- Implemented 3-frame jump sequence
- Added landing state transition
- Fixed animation loop bug"
```

### 5. マージ済みのブランチを削除する

マージ後、整理します：

```bash theme={null}
# ローカル参照を削除
dv branch -d feature-ui

# ブランチの履歴は main に保持されます
```

***

## 一般的なブランチワークフロー

### 機能ブランチワークフロー

適用対象：複数の機能を同時に開発するチーム

```bash theme={null}
# 1. main から機能ブランチを作成
dv checkout main
dv branch -c feature/new-weapon

# 2. 機能を開発
dv checkout feature/new-weapon
# ... 変更を加える ...
dv commit -a -m "Add new weapon model"

# 3. 機能を main と最新の状態に保つ
dv merge main

# 4. 準備ができたら、main にマージするか Review を作成する
dv checkout main
dv merge feature/new-weapon

# 5. 機能ブランチを削除
dv branch -d feature/new-weapon
```

### リリースブランチワークフロー

適用対象：複数のリリースバージョンの管理

```bash theme={null}
# main からリリースブランチを作成
dv checkout main
dv branch -c release/v1.0

# バグ修正はリリースブランチへ
dv checkout release/v1.0
dv commit -a -m "Fix critical save bug"

# 修正を main にマージバック
dv checkout main
dv merge release/v1.0

# リリースブランチは v1.0.x パッチ用に残る
```

### ホットフィックスワークフロー

適用対象：緊急の本番修正

```bash theme={null}
# リリースブランチからホットフィックスを作成
dv checkout release/v1.0
dv branch -c hotfix/save-crash

# バグを修正
dv checkout hotfix/save-crash
dv commit -a -m "Fix save crash in level 3"

# リリースにマージ
dv checkout release/v1.0
dv merge hotfix/save-crash

# main にもマージ
dv checkout main
dv merge hotfix/save-crash

# ホットフィックスブランチを削除
dv branch -d hotfix/save-crash
```

***

## トラブルシューティング

### 「Cannot switch branches: uncommitted changes」

**問題：** ワークスペースにコミットされていない変更があります。

**解決方法：**

```bash theme={null}
# オプション 1: 変更をコミットする
dv commit -a -m "WIP: save progress"

# オプション 2: 変更を破棄する
dv checkout --force branch-name  # 注意：変更が失われます！

# オプション 3: シェルビングを使用する（後のために保存）
# (シェルビングガイドは近日公開)
```

### 「Merge conflict in multiple files」

**問題：** 多くのファイルに競合があります。

**解決方法：**

1. 一度に1ファイルずつ競合を解決する
2. `dv status` を使用して進捗を追跡する
3. 重要でないファイルには片方を受け入れることを検討する
4. 重要なファイルは手動でマージする

### 「Branch already exists」

**問題：** ブランチ名が既に使用されています。

**解決方法：**

```bash theme={null}
# 別の名前を使用する
dv branch -c feature/new-ui-v2

# または、古いブランチを先に削除する
dv branch -d feature/new-ui
dv branch -c feature/new-ui
```

***

## CLI リファレンス

**ブランチ管理：**

```bash theme={null}
dv branch                    # ブランチ一覧
dv branch -c <name>          # ブランチ作成
dv branch -d <name>          # ブランチ削除
dv branch -r <old> <new>     # ブランチ名変更
dv checkout <branch>         # ブランチに切り替え
```

**マージ：**

```bash theme={null}
dv merge <source>            # ブランチをマージ
```

**ステータス：**

```bash theme={null}
dv status                    # 現在のブランチと変更を表示
dv log                       # コミット履歴を表示
dv diff                      # コミットされていない変更を表示
```

[完全な CLI リファレンス](/ja/cmd-ref/branch)

***

## 関連リソース

**コアコンセプト：**

* [リポジトリ、ブランチ、ワークスペース](/ja/concepts/repo-branch-workspace)
* [競合を理解する](/ja/concepts/conflicts)
* [同期の仕組み](/ja/concepts/syncing)

**ワークフロー：**

* [並行作業](/ja/basic/working-in-parallel)
* [コードレビュー](/ja/basic/reviews)

**CLI リファレンス：**

* [branch コマンド](/ja/cmd-ref/branch)
* [checkout コマンド](/ja/cmd-ref/checkout)
* [merge コマンド](/ja/cmd-ref/merge)
* [commit コマンド](/ja/cmd-ref/commit)

***

**最終更新：** 2025-10-26