Branching Like a Pro: Experiment Without Breaking Things

The complete guide to Git-like branching for game design documents

Read Time: 20 minutes

§Introduction: The Fear of Experimentation#

Every game designer has felt this: you have an idea that might be brilliant or might be terrible. Maybe you want to completely reimagine the combat system. Maybe you want to double all the cooldowns to see what happens. Maybe you want to try a totally different progression curve.

But you're afraid to try it.

Why? Because the current design doc works. People are implementing from it. If you break it with your experiment, you break the whole team's workflow. So the idea stays in your head, untested, forever.

Branching eliminates this fear.

With branches, you can create a parallel version of any document, experiment wildly, and then decide: merge the changes if they work, or delete the branch if they don't. The main document stays untouched until you're ready.

This is how software developers have worked for decades. Now it's how you can work too.

§Part 1: Understanding Branches#

What Is a Branch?#

A branch is a parallel version of a document that diverges from the "main" version. Think of it like a choose-your-own-adventure book where you can explore a path without committing to it.

Visual metaphor:

        ┌── ability-rework (your experiment)
       /
main ─────────────────────── (stable, everyone uses this)
       \
        └── economy-balance (someone else's experiment)

Each branch has its own version history. Changes on one branch don't affect others.

The Main Branch#

Every document has a "main" branch (sometimes called "trunk" or "master"). This is:

• —The default branch everyone sees
• —The stable version people implement from
• —The source that branches are created from
• —The target that branches merge back into

Rule of thumb: Main should always be "production-ready." If someone implements from main right now, it should work.

Branch Lifecycle#

1. 1.Create - Branch off from main (or another branch)
2. 2.Edit - Make changes on your branch
3. 3.Review - Verify your changes work
4. 4.Merge - Bring changes back to main
5. 5.Delete - Clean up the branch

§Part 2: Why Use Branches?#

Use Case 1: Safe Experimentation#

Scenario: You want to test removing the shield mechanic and adding a dodge roll instead.

Without branches:

• —Edit the main design doc
• —Team sees half-baked changes
• —If experiment fails, manually undo everything
• —Hope you didn't break anything

With branches:

1. 1.Create branch: "experiment-dodge-mechanic"
2. 2.Rewrite combat section with dodge
3. 3.Playtest with the experimental version
4. 4.If it works: merge to main
5. 5.If it doesn't: delete the branch
6. 6.Main was never touched

Use Case 2: Parallel Development#

Scenario: Sarah is rebalancing abilities while Mike rewrites the tutorial section. Both need to edit the same core design doc.

Without branches:

• —They step on each other's changes
• —"Did you overwrite my edit?"
• —Constant coordination overhead
• —Someone's work gets lost

With branches:

1. 1.Sarah creates branch: "ability-rebalance"
2. 2.Mike creates branch: "tutorial-rewrite"
3. 3.Both work independently
4. 4.When ready, each merges to main
5. 5.Conflicts (if any) are handled explicitly

Use Case 3: Review Workflows#

Scenario: You need stakeholder approval on design changes before they're "official."

Without branches:

• —Make changes to main
• —Hope stakeholders review quickly
• —Main is in limbo—neither old nor approved-new

With branches:

1. 1.Create branch: "q4-combat-changes"
2. 2.Make all your changes there
3. 3.Share branch with stakeholders for review
4. 4.Main stays stable for the team
5. 5.After approval, merge to main

Use Case 4: What-If Analysis#

Scenario: "What if we doubled all cooldowns? Would combat feel better?"

With branches:

1. 1.Create branch: "double-cooldowns-test"
2. 2.Find/replace all cooldown values
3. 3.Generate a playtest build from this branch
4. 4.Analyze results
5. 5.Keep or discard based on data

You can have multiple "what-if" branches simultaneously, comparing different approaches.

Use Case 5: Rollback Safety#

Scenario: You merged a change that broke game balance. Need to undo immediately.

With branches:

• —The pre-merge main still exists in version history
• —Create a new branch from the old version
• —Cherry-pick what to keep
• —Replace main with the fixed version

§Part 3: Creating Branches#

Step-by-Step: Your First Branch#

1. 1.Open the document you want to branch
2. 2.Find the Branch Selector in the toolbar (shows current branch, usually "main")
3. 3.Click the dropdown to see all branches
4. 4.Click "Create New Branch"
5. 5.Enter details:

- Name: Use a clear, descriptive name (see naming conventions below)

- Description: Explain what this branch is for

- Base: Usually "main" (or branch from another branch)

1. 1.Click Create

You're now on your new branch. The branch selector shows your branch name.

What Happens When You Create a Branch#

1. 1.A snapshot of the current document state is taken
2. 2.A new timeline is created branching from that point
3. 3.You're switched to the new branch
4. 4.Future edits go to this branch, not main

The original branch (main) is unchanged. You can switch back anytime.

Branch Naming Conventions#

Good names make branches manageable. Use patterns like:

Avoid:

• —"test", "branch1", "changes", "new"
• —Spaces (use hyphens)
• —Special characters

Branch Descriptions#

When creating a branch, write a meaningful description:

Bad:

• —"Testing stuff"
• —""(empty)

Good:

• —"Exploring whether removing shields and adding dodge improves combat flow. Will playtest on Dec 15."
• —"Rebalancing all warrior abilities based on Nov playtest feedback. See JIRA-1234."

The description appears in branch listings, helping teammates understand what's happening.

§Part 4: Working on Branches#

Editing on a Branch#

Once you're on a branch, edit normally:

1. 1.Click Edit
2. 2.Make your changes
3. 3.Click Save
4. 4.Enter a change description (as always)

The key difference: changes go to your branch, not main. Main is unaffected.

Switching Between Branches#

Use the Branch Selector to switch:

1. 1.Click the branch selector (shows current branch name)
2. 2.See list of all branches
3. 3.Click the branch you want
4. 4.Document updates to show that branch's version

Your work is saved. Switching branches doesn't lose anything. Each branch remembers its state.

Viewing Branch History#

Each branch has its own version history:

1. 1.Open History panel
2. 2.Note: you're seeing history for the CURRENT branch
3. 3.To see another branch's history, switch to it first

Comparing Branches#

Before merging, compare what's different:

1. 1.Open the Branch Selector
2. 2.Click Compare on your branch
3. 3.Select which branch to compare against (usually main)
4. 4.See a diff of all changes

This shows you exactly what will change when you merge.

§Part 5: Merging Branches#

When to Merge#

Merge when your branch's changes are ready for the main document:

• —Experiment succeeded
• —Feature is complete
• —Review was approved
• —Fix is verified

Step-by-Step: Merging#

1. 1.Open the Branch Selector
2. 2.Click the ⋯ menu next to your branch
3. 3.Click "Merge"
4. 4.Select target branch (usually "main")
5. 5.Preview the merge:

- See all changes that will be applied

- Green = additions

- Red = deletions

- Yellow = modifications

1. 1.Add a merge message describing what's being merged
2. 2.Click "Confirm Merge"

Your changes are now in main.

What Happens During Merge#

1. 1.Gameframe compares your branch to the target
2. 2.All changes are applied to the target
3. 3.A new version is created on the target with merge info
4. 4.Your branch still exists (you can delete it now)

Fast-Forward vs. Regular Merges#

Fast-forward merge: Main hasn't changed since you branched. Your changes simply become the new main. Clean and simple.

Regular merge: Main has changed. Both sets of changes are combined. May require conflict resolution.

After Merging#

1. 1.Verify the merge: Check main looks correct
2. 2.Delete the branch: Keep your workspace clean
3. 3.Notify team: "Merged ability-rebalance, main updated"

§Part 6: Handling Merge Conflicts#

What Is a Conflict?#

A conflict happens when two branches change the same lines differently. Gameframe can't automatically decide which version is correct.

Example:

Main was changed:

player_health: 120  (was 100)

Your branch was changed:

player_health: 150  (was 100)

Both changed player_health from 100, but to different values. Conflict.

How Conflicts Appear#

When you try to merge a conflicting branch, Gameframe:

1. 1.Pauses the merge
2. 2.Shows you the conflicting sections
3. 3.Asks you to resolve each conflict

Conflict markers look like:

<<<<<<< main
player_health: 120
=======
player_health: 150
>>>>>>> ability-rework

Resolving Conflicts#

For each conflict, you have options:

1. 1.Keep main's version: Accept 120
2. 2.Keep your version: Accept 150
3. 3.Keep both: Maybe doesn't make sense here
4. 4.Custom resolution: Type 135 (a compromise)

After resolving all conflicts:

1. 1.Click "Mark Resolved"
2. 2.Review the final merged version
3. 3.Click "Complete Merge"

Avoiding Conflicts#

Conflicts aren't errors—they're a normal part of collaboration. But you can minimize them:

1. 1.Merge frequently: Don't let branches diverge too far
2. 2.Keep branches focused: One purpose per branch
3. 3.Communicate: "I'm editing the combat section today"
4. 4.Small changes: Many small merges > one huge merge

§Part 7: Branching Strategies#

Different teams use different approaches. Here are proven patterns:

Strategy 1: Feature Branches#

How it works:

• —Main is always stable
• —Each feature/experiment gets its own branch
• —Merge to main when feature is complete

Branch structure:

main (stable)
├── feature-dodge-mechanic
├── feature-new-abilities
└── experiment-economy-rebalance

Best for: Most teams. Simple and effective.

Strategy 2: GitFlow-Style#

How it works:

• —Main = production/shipped
• —Develop = integration branch
• —Features branch from develop
• —Releases branch from develop

Branch structure:

main (shipped version)
└── develop (next release)
    ├── feature-A
    ├── feature-B
    └── release-1.2 (being prepared)

Best for: Teams with formal release cycles.

Strategy 3: Personal Branches#

How it works:

• —Each designer has their own branch
• —Work happens on personal branches
• —Merge to main after review

Branch structure:

main (approved content)
├── sarah-wip
├── mike-wip
└── alex-wip

Best for: Small teams, informal review processes.

Strategy 4: Environment Branches#

How it works:

• —Main = production design
• —Staging = under review
• —Feature branches merge to staging first

Branch structure:

main (implemented)
└── staging (under review)
    └── feature-X (in development)

Best for: Teams with stakeholder review requirements.

§Part 8: Best Practices#

1. Keep Branches Short-Lived#

Guideline:

• —Ideal: 1-5 days
• —Acceptable: 1-2 weeks
• —Problematic: 1+ month

Long-running branches diverge from main, causing merge conflicts and integration pain.

2. Merge Main into Your Branch Regularly#

If main is getting updates while you work:

1. 1.Stay on your branch
2. 2.Merge main INTO your branch periodically
3. 3.Resolve any conflicts early
4. 4.When you merge back, it's clean

3. One Purpose Per Branch#

Each branch should have a single, clear purpose:

Good:

• —"Rebalance warrior abilities"
• —"Add dodge mechanic"
• —"Update tutorial section"

Bad:

• —"Various fixes and updates"
• —"My changes"
• —"Q4 work"

4. Delete Merged Branches#

After merging, delete the branch. Keep your workspace clean.

Exception: Keep branches for major milestones ("pre-release-1.0") for easy reference.

5. Use Branch Descriptions#

When creating a branch, always add a description. Future you (and teammates) will appreciate it.

6. Communicate About Branches#

Let your team know:

• —What branches exist and why
• —Who's working on what
• —When you plan to merge
• —If you need input before merging

§Part 9: Troubleshooting#

"I made changes to the wrong branch"#

1. 1.Create a new branch from where you are now
2. 2.Switch to the correct branch
3. 3.Cherry-pick the specific changes (or merge from your temp branch)
4. 4.Delete the temp branch

"My merge has too many conflicts"#

1. 1.Abort the merge
2. 2.Update your branch by merging main INTO it first
3. 3.Resolve conflicts in smaller chunks
4. 4.Then merge back to main

"I deleted a branch I need"#

If you have merge request history or backups:

1. 1.Check the merge request for branch contents
2. 2.Create a new branch with the same name
3. 3.Restore from backup if available

Prevention: Don't delete branches until you're SURE you're done.

"Main was broken by a merge"#

1. 1.Identify the problematic merge in version history
2. 2.Create a branch from the pre-merge version
3. 3.Apply any good changes that came after
4. 4.Replace main with your fixed branch

§Part 10: Quick Reference#

Creating a Branch#

1. 1.Open document
2. 2.Branch Selector → Create New Branch
3. 3.Enter name and description
4. 4.Click Create

Merging a Branch#

1. 1.Branch Selector → ⋯ → Merge
2. 2.Select target (usually main)
3. 3.Review changes
4. 4.Resolve conflicts if any
5. 5.Confirm Merge

Branch Commands#

Keyboard Shortcuts#

§Summary#

Branching transforms how you work with design documents:

• —Experiment fearlessly — Try ideas without risk
• —Work in parallel — Multiple designers, no collisions
• —Review before committing — Stakeholder approval workflow
• —Maintain stability — Main is always reliable

The mental shift: Your documents are no longer fragile files that everyone's afraid to touch. They're robust, version-controlled resources that support experimentation and collaboration.

That's the power of branching. That's how professionals manage design.

Continue learning:

• —Version Control 101 - Master the fundamentals of document versioning
• —Contractor Access Setup - Manage team permissions securely
• —Quest Log Mastery - Integrate task tracking with your documents

Ready to experiment? Start your free trial and create your first branch today.