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:

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

Creating Branches

You can also create branches in the Desktop App.

Create a New Branch

Create a branch from your current position:

dv branch -c feature-name

What happens:

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

Example:

# 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

# 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

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.

Checkout a Branch

Switch your workspace to a different branch:

dv checkout feature-name

What happens:

Diversion updates your workspace files to match the target branch
Your local files change to reflect the branch’s state
Any new commits will go to this branch

Example workflow:

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

Before switching branches:

Commit discard or shelf your current changes
Diversion will warn you if you have uncommitted changes
Use dv status to check for pending changes

Merging Branches

You can also merge branches in the Desktop App. 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

Switch to target branch

First, check out the branch you want to merge into:

dv checkout main

Merge the source branch

Merge the feature branch into main:

dv merge feature-ui

Resolve conflicts (if any)

If there are conflicts, Diversion will guide you through resolution:

# View conflicts
dv status

# After resolving conflicts in your editor
dv commit -a -m "Merge feature-ui into main"

Delete the feature branch (optional)

After merging, you can delete the feature branch:

dv branch -d feature-ui

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:

Diversion finds the common ancestor (commit B)
Compares changes from B→C (main’s changes)
Compares changes from B→E (feature’s changes)
Intelligently combines both sets of changes
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

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

Resolving Conflicts

When conflicts do occur, Diversion makes resolution straightforward:

Identify conflicting files

dv merge feature-ui
# Output: Conflict in src/player.cpp

dv status
# Shows: Conflicted files

Open conflicting files

Conflict markers show both versions:

<<<<<<< HEAD (main)
int speed = 100;
=======
int speed = 150;
>>>>>>> feature-ui

Choose or combine changes

Edit the file to resolve the conflict:

// Choose one side
int speed = 150;

// Or combine
int speed = 125; // Compromise between branches

Mark as resolved

Commit the resolved merge:

dv commit -a -m "Merge feature-ui: resolve speed conflict"

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:

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:

# 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

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

# 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

# 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

# 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

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

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

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

”Branch already exists”

Problem: Branch name is taken. Solution:

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

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:

dv merge <source>            # Merge branch

Status:

dv status                    # Show current branch and changes
dv log                       # Show commit history
dv diff                      # Show uncommitted changes

Full CLI reference

Core Concepts:

Workflows:

CLI Reference:

Last updated: 2025-10-26

​Branching and Merging

​What are Branches?

​Understanding Branches vs Workspaces

​Creating Branches

​Create a New Branch

​Create a Branch from a Specific Commit

​List All Branches

​Switching Between Branches

​Checkout a Branch

​Merging Branches

​Basic Merge Workflow

​How Merging Works

​Merge Strategies

​Handling Merge Conflicts

​Conflict Detection

​Resolving Conflicts

​Conflict Resolution Options

​Branching Best Practices

​1. Branch Naming Conventions

​2. Keep Branches Short-Lived

​3. Merge Frequently

​4. Use Descriptive Commit Messages

​5. Delete Merged Branches

​Common Branching Workflows

​Feature Branch Workflow

​Release Branch Workflow

​Hotfix Workflow

​Troubleshooting

​”Cannot switch branches: uncommitted changes”

​“Merge conflict in multiple files”

​”Branch already exists”

​CLI Reference

​Related Resources

Branching and Merging

What are Branches?

Understanding Branches vs Workspaces

Creating Branches

Create a New Branch

Create a Branch from a Specific Commit

List All Branches

Switching Between Branches

Checkout a Branch

Merging Branches

Basic Merge Workflow

How Merging Works

Merge Strategies

Handling Merge Conflicts

Conflict Detection

Resolving Conflicts

Conflict Resolution Options

Branching Best Practices

1. Branch Naming Conventions

2. Keep Branches Short-Lived

3. Merge Frequently

4. Use Descriptive Commit Messages

5. Delete Merged Branches

Common Branching Workflows

Feature Branch Workflow

Release Branch Workflow

Hotfix Workflow

Troubleshooting

”Cannot switch branches: uncommitted changes”

“Merge conflict in multiple files”

”Branch already exists”

CLI Reference

Related Resources