> ## 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.

# Branching and Merging

> Learn how branching and merging work in Diversion, including creating branches, switching between branches, and resolving merge conflicts.

# Branching and Merging

Branching and merging in Diversion allows teams to work on multiple features in parallel while maintaining a stable main branch. With lightning-fast branch creation (milliseconds) and smart merging, Diversion makes parallel development effortless.

## What are Branches?

A **branch** is an independent line of development in your repository. Branches allow you to:

* Work on features without affecting the main codebase
* Experiment with changes safely
* Collaborate on separate tasks simultaneously
* Maintain stable release versions while developing new features

**Key characteristics in Diversion:**

* Branch creation takes milliseconds, regardless of repository size
* Branches are server-side (cloud-based)
* All team members can see all branches
* No file copying or duplication

## Understanding Branches vs Workspaces

Before diving into branching, it's important to understand how branches relate to workspaces:

| Concept       | Purpose                         | Visibility       | Typical Lifespan        |
| ------------- | ------------------------------- | ---------------- | ----------------------- |
| **Branch**    | Independent line of development | All team members | Days to weeks           |
| **Workspace** | Your local working environment  | Only you         | Entire project duration |

**Think of it this way:**

* **Branch** = Where the code lives (like `main`, `feature-ui`, `bugfix-123`)
* **Workspace** = Your personal workbench (where you edit files locally)

**Example workflow:**

```bash theme={null}
# Your workspace points to the 'main' branch
dv checkout main

# Create a new feature branch
dv branch -c feature-ui

# Switch your workspace to the new branch
dv checkout feature-ui

# Make changes in your workspace
# ... edit files ...

# Commit to the feature-ui branch
dv commit -a -m "Add new UI components"
```

[Learn more about workspaces →](/concepts/repo-branch-workspace)

***

## Creating Branches

You can also [create branches in the Desktop App](/basic/working-in-parallel#creating-a-new-branch).

### Create a New Branch

Create a branch from your current position:

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

**What happens:**

1. Diversion creates a new branch pointing to your current commit
2. The branch is immediately available to all team members
3. Creation takes \~100ms regardless of repository size

**Example:**

```bash theme={null}
# Create a branch for a new feature
dv branch -c feature-new-level

# Create a branch for a bug fix
dv branch -c bugfix-character-movement
```

### Create a Branch from a Specific Commit

```bash theme={null}
# First, find the commit ID
dv log

# Check out commit
dv checkout <commit-id>

# Create a new branch
dv branch -c feature-name 
```

### List All Branches

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

**Output example:**

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

The `*` indicates your workspace's current branch.

***

## Switching Between Branches

You can also [switch branches in the Desktop App](/basic/working-in-parallel#switching-branches).

### Checkout a Branch

Switch your workspace to a different branch:

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

**What happens:**

1. Diversion updates your workspace files to match the target branch
2. Your local files change to reflect the branch's state
3. Any new commits will go to this branch

**Example workflow:**

```bash theme={null}
# Check which branch you're on
dv status

# Switch to main branch
dv checkout main

# Switch to feature branch
dv checkout feature-new-level

# Make changes and commit
dv commit -a -m "Add level geometry"
```

<Warning>
  **Before switching branches:**

  * Commit discard or [shelf](/core-concepts/shelving) your current changes
  * Diversion will warn you if you have uncommitted changes
  * Use `dv status` to check for pending changes
</Warning>

***

## Merging Branches

You can also [merge branches in the Desktop App](/basic/working-in-parallel#how-to-merge).

Merging integrates changes from one branch into another. Diversion supports smart merging with automatic conflict detection.

### Basic Merge Workflow

**Goal:** Merge `feature-ui` into `main`

<Steps>
  <Step title="Switch to target branch">
    First, check out the branch you want to merge **into**:

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

  <Step title="Merge the source branch">
    Merge the feature branch into main:

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

  <Step title="Resolve conflicts (if any)">
    If there are conflicts, Diversion will guide you through resolution:

    ```bash theme={null}
    # View conflicts
    dv status

    # After resolving conflicts in your editor
    dv commit -a -m "Merge feature-ui into main"
    ```
  </Step>

  <Step title="Delete the feature branch (optional)">
    After merging, you can delete the feature branch:

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

### How Merging Works

Diversion uses **3-way merge** with common ancestor detection:

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

**When you run `dv merge feature-ui` from main:**

1. Diversion finds the **common ancestor** (commit B)
2. Compares changes from B→C (main's changes)
3. Compares changes from B→E (feature's changes)
4. Intelligently combines both sets of changes
5. Creates a new merge commit:

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

**Benefits:**

* Preserves history from both branches
* Accurately detects conflicts
* Maintains complete audit trail

### Merge Strategies

**Regular Merge (Default):**

* Preserves all commits from both branches
* Creates a merge commit
* Complete history visible in `dv log`

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

**When to merge:**

* You want complete history
* Feature commits are significant milestones
* You need to track who made each change

***

## Handling Merge Conflicts

The Desktop App provides a visual conflict resolution tool — see [Merge Conflicts in the Desktop App](/basic/working-in-parallel#merge-conflicts).

Merge conflicts occur when the same lines of code are changed in both branches.

### Conflict Detection

Diversion prevents conflicts before they happen:

**Real-time notifications:**

* See who's editing which files
* Get notified when teammates modify files you're working on
* Coordinate changes before conflicts occur

[Learn more about conflict prevention →](/concepts/conflicts)

### Resolving Conflicts

When conflicts do occur, Diversion makes resolution straightforward:

<Steps>
  <Step title="Identify conflicting files">
    ```bash theme={null}
    dv merge feature-ui
    # Output: Conflict in src/player.cpp

    dv status
    # Shows: Conflicted files
    ```
  </Step>

  <Step title="Open conflicting files">
    Conflict markers show both versions:

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

  <Step title="Choose or combine changes">
    Edit the file to resolve the conflict:

    ```cpp theme={null}
    // Choose one side
    int speed = 150;

    // Or combine
    int speed = 125; // Compromise between branches
    ```
  </Step>

  <Step title="Mark as resolved">
    Commit the resolved merge:

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

### Conflict Resolution Options

**Accept one side completely:**

Via Web UI or API:

* Accept "ours" (keep main's version)
* Accept "theirs" (use feature branch's version)
* Accept all conflicts at once

**Manual resolution:**

* Edit files to combine changes
* Commit when satisfied

***

## Branching Best Practices

### 1. Branch Naming Conventions

Use descriptive, consistent names:

**Good examples:**

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

**Naming patterns:**

* `feature/` - New features
* `bugfix/` - Bug fixes
* `hotfix/` - Urgent production fixes
* `release/` - Release branches
* `experimental/` - Experimental work

### 2. Keep Branches Short-Lived

**Why:**

* Reduces merge conflicts
* Easier to review changes
* Faster integration

**How:**

* Merge feature branches within days, not weeks
* Delete branches after merging
* Create small, focused branches

### 3. Merge Frequently

Merge `main` into your feature branch regularly:

```bash theme={null}
# In your feature branch
dv checkout feature-ui
dv merge main

# This keeps your feature up-to-date with main
```

**Benefits:**

* Smaller, easier merges
* Catch conflicts early
* Feature stays compatible with latest main

### 4. Use Descriptive Commit Messages

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

# Better
dv commit -m "Add character jump animation

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

### 5. Delete Merged Branches

After merging, clean up:

```bash theme={null}
# Delete local reference
dv branch -d feature-ui

# Branch history is preserved in main
```

***

## Common Branching Workflows

### Feature Branch Workflow

Best for: Teams developing multiple features simultaneously

```bash theme={null}
# 1. Create feature branch from main
dv checkout main
dv branch -c feature/new-weapon

# 2. Develop feature
dv checkout feature/new-weapon
# ... make changes ...
dv commit -a -m "Add new weapon model"

# 3. Keep feature updated with main
dv merge main

# 4. When ready, merge to main or create a Review
dv checkout main
dv merge feature/new-weapon

# 5. Delete feature branch
dv branch -d feature/new-weapon
```

### Release Branch Workflow

Best for: Managing multiple release versions

```bash theme={null}
# Create release branch from main
dv checkout main
dv branch -c release/v1.0

# Bug fixes go to release branch
dv checkout release/v1.0
dv commit -a -m "Fix critical save bug"

# Merge fixes back to main
dv checkout main
dv merge release/v1.0

# Release branch stays for v1.0.x patches
```

### Hotfix Workflow

Best for: Urgent production fixes

```bash theme={null}
# Create hotfix from release branch
dv checkout release/v1.0
dv branch -c hotfix/save-crash

# Fix the bug
dv checkout hotfix/save-crash
dv commit -a -m "Fix save crash in level 3"

# Merge to release
dv checkout release/v1.0
dv merge hotfix/save-crash

# Also merge to main
dv checkout main
dv merge hotfix/save-crash

# Delete hotfix branch
dv branch -d hotfix/save-crash
```

***

## Troubleshooting

### "Cannot switch branches: uncommitted changes"

**Problem:** You have uncommitted changes in your workspace.

**Solution:**

```bash theme={null}
# Option 1: Commit your changes
dv commit -a -m "WIP: save progress"

# Option 2: Discard changes
dv checkout --force branch-name  # Careful: loses changes!

# Option 3: Use shelving (save for later)
# (Shelving guide coming soon)
```

### "Merge conflict in multiple files"

**Problem:** Many files have conflicts.

**Solution:**

1. Resolve conflicts one file at a time
2. Use `dv status` to track progress
3. Consider accepting one side for non-critical files
4. Manually merge important files

### "Branch already exists"

**Problem:** Branch name is taken.

**Solution:**

```bash theme={null}
# Use a different name
dv branch -c feature/new-ui-v2

# Or delete the old branch first
dv branch -d feature/new-ui
dv branch -c feature/new-ui
```

***

## CLI Reference

**Branch Management:**

```bash theme={null}
dv branch                    # List branches
dv branch -c <name>          # Create branch
dv branch -d <name>          # Delete branch
dv branch -r <old> <new>     # Rename branch
dv checkout <branch>         # Switch to branch
```

**Merging:**

```bash theme={null}
dv merge <source>            # Merge branch
```

**Status:**

```bash theme={null}
dv status                    # Show current branch and changes
dv log                       # Show commit history
dv diff                      # Show uncommitted changes
```

[Full CLI reference](/cmd-ref/branch)

***

## Related Resources

**Core Concepts:**

* [Repositories, Branches, and Workspaces](/concepts/repo-branch-workspace)
* [Understanding Conflicts](/concepts/conflicts)
* [How Syncing Works](/concepts/syncing)

**Workflows:**

* [Working in Parallel](/basic/working-in-parallel)
* [Code Review](/basic/reviews)

**CLI Reference:**

* [branch command](/cmd-ref/branch)
* [checkout command](/cmd-ref/checkout)
* [merge command](/cmd-ref/merge)
* [commit command](/cmd-ref/commit)

***

**Last updated:** 2025-10-26