Skip to main content

​
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:
ConceptPurposeVisibilityTypical Lifespan
BranchIndependent line of developmentAll team membersDays to weeks
WorkspaceYour local working environmentOnly youEntire 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

​
Create a New Branch

Create a branch from your current position: 
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: 
# 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

# Create branch from that commit
dv branch -c hotfix-v1.0 <commit-id>

​
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

​
Checkout a Branch

Switch your workspace to a different branch: 
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: 
# 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

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
1

Switch to target branch

First, check out the branch you want to merge into:
dv checkout main
2

Merge the source branch

Merge the feature branch into main:
dv merge feature-ui
3

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

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

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

Identify conflicting files

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

dv status
# Shows: Conflicted files
2

Open conflicting files

Conflict markers show both versions:
<<<<<<< HEAD (main)
int speed = 100;
=======
int speed = 150;
>>>>>>> feature-ui
3

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
4

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