Branching & Merging

Branches let you work on different versions of your project simultaneously. Create branches for experiments, features, or different edit versions.

Why Use Branches?

In video production, branches are invaluable for:

Client versions: Maintain different cuts for different stakeholders
Experiments: Try color grades or edits without affecting the main project
Collaboration: Work on different scenes simultaneously
Releases: Maintain stable releases while continuing development

Branch Basics

Create

dits branch name creates a new branch pointing to the current commit.

Switch

dits switch name moves to a different branch, updating your working directory.

Merge

dits merge name combines changes from another branch into your current branch.

Creating Branches

# Create a new branch
$ dits branch client-version

# Create and switch in one command
$ dits switch -c client-version

# Create from a specific commit
$ dits branch hotfix a1b2c3d

# List all branches
$ dits branch --list
* main
  client-version
  color-grade-experiment

Switching Branches

$ dits switch client-version

Switched to branch 'client-version'
Hydrating 3 changed files... done

$ dits status
On branch client-version

Efficient Branch Switching

Unlike Git with large files, switching branches in Dits only hydrates files that differ between branches. Switching between branches with mostly the same content is nearly instant.

Branch Visualization

$ dits log --graph --oneline --all

* f5e4d3c (HEAD -> main) Final delivery
| * c4d5e6f (client-version) Client revisions
| * b3c4d5e Add client logo
|/
* a1b2c3d Color grading complete
| * 9a8b7c6 (experiment/new-grade) Try film look
|/
* 8f7e6d5 Initial edit

Merging Branches

Fast-Forward Merge

When there are no divergent changes, Dits simply moves the branch pointer:

$ dits switch main
$ dits merge feature/audio

Updating a1b2c3d..f5e4d3c
Fast-forward
 audio/sound-effects.wav | new file
 audio/music.wav         | new file
 2 files changed, 500 MB added

Three-Way Merge

When both branches have changes, Dits creates a merge commit:

$ dits merge client-version

Auto-merging project files...
Merge made by the 'ort' strategy.
 project.prproj | modified
 1 file changed

Handling Conflicts

For binary files like videos, Dits uses file-level conflict resolution rather than trying to merge content:

$ dits merge client-version

CONFLICT (content): Merge conflict in footage/scene1.mov
Automatic merge failed; fix conflicts and then commit.

$ dits status
On branch main
You have unmerged paths.
  (fix conflicts and run "dits commit")

Unmerged paths:
  both modified: footage/scene1.mov

Resolving Conflicts

# Keep the version from main (ours)
$ dits checkout --ours footage/scene1.mov

# Keep the version from client-version (theirs)
$ dits checkout --theirs footage/scene1.mov

# Or manually place the file you want, then:
$ dits add footage/scene1.mov
$ dits commit -m "Merge client-version, keep our scene1"

File Locking

For large binary files, prevention is better than resolution. Dits supports file locking to prevent conflicts:

Advisory Locks

Signal to teammates that you're working on a file. Others can still edit but will see a warning.

dits lock footage/scene1.mov

Strict Locks

Prevent others from editing the file entirely until you release the lock.

dits lock --strict footage/scene1.mov

# Lock a file
$ dits lock footage/scene1.mov
Locked 'footage/scene1.mov'

# See who has locks
$ dits lock --list
footage/scene1.mov    locked by jane@example.com    2 hours ago

# Unlock when done
$ dits unlock footage/scene1.mov
Unlocked 'footage/scene1.mov'

Branch Strategies

Feature Branches

Create a branch for each distinct piece of work:

main

feature/scene1-color

feature/scene2-audio

feature/titles

feature/credits

Client/Version Branches

Maintain different versions for different audiences:

mainmaster edit

version/theatrical

version/streaming

version/tv-broadcast

version/airline

Release Branches

Stabilize releases while continuing development:

maindevelopment

release/v1.0

release/v1.1

release/v2.0

Deleting Branches

# Delete a merged branch
$ dits branch -d feature/completed
Deleted branch feature/completed.

# Force delete an unmerged branch
$ dits branch -D experiment/abandoned
Deleted branch experiment/abandoned.

# Delete a remote branch
$ dits push origin --delete feature/completed

Rebasing

Rebase replays your changes on top of another branch, creating a linear history:

$ dits switch feature/audio
$ dits rebase main

Rebasing (1/3): Add sound effects
Rebasing (2/3): Add music track
Rebasing (3/3): Adjust audio levels

Successfully rebased and updated refs/heads/feature/audio.

When to Rebase vs Merge

Rebase: For local branches to keep history clean
Merge: For shared branches or preserving history
Never rebase branches that others are using

Cherry-Picking

Apply specific commits from other branches:

# Apply a single commit to current branch
$ dits cherry-pick a1b2c3d

[main f6g7h8i] Add sound effects
 1 file changed, 150 MB added

# Cherry-pick multiple commits
$ dits cherry-pick a1b2c3d b2c3d4e c3d4e5f