Branching & Version Control

What is Branching?

Branching lets you create parallel versions of your project to test different ideas independently. Perfect for rapid prototyping - try multiple design directions, compare variations, and collaborate without affecting your main project.

Main branch:  A---B---C---D---E

                   \

New branch          X---Y---Z

Key benefits:

• Safe experimentation - Try changes without risk

• Work in parallel - Multiple people on different versions simultaneously

• Quick iteration - Test design variations before committing

• Independent state - Each branch has its own checkpoints and chat history

Important: Branches cannot yet be merged. This feature is in development. For now, use branches to compare approaches, then manually implement your chosen direction in the main branch.

Creating Branches

There are two ways to create branches in Onlook: from the canvas or from the Branches panel.

From the Canvas

The fastest way to branch while working.

How to create:

1. Look at the top of the canvas window

2. Click the current branch name

3. Select "Create new branch"

4. Name your branch

5. You're now working in the new branch

The new branch starts with your current project state.

From the Branches Panel

Create and manage all branches from one location.

How to create:

1. Open the Branches panel in the left sidebar

2. Click "Create branch"

3. Choose which branch to branch off from

4. Name your new branch

5. Click create

Branching off any branch:

You can create a new branch from any existing branch, not just main. This lets you:

• Try variations of an experiment

• Test different approaches from the same starting point

• Build on another team member's work

Switching Between Branches

Move between branches to view different versions of your project.

From the Canvas

How to switch:

1. 1. Click the branch name at the top of the canvas

2. Select the branch you want to switch to

3. Your project loads with that branch's state

From the Branches Panel

How to switch:

1. Open the Branches panel

2. View all available branches

3. Click the branch you want to work on

4. The canvas updates to show that branch

When you switch branches:

• All your work in the current branch is automatically saved

• The canvas loads the selected branch's latest state

• AI chat shows that branch's history

• Checkpoints reflect that branch's restore points

Managing Branches

The Branches panel is your control center for all branch operations.

Viewing All Branches

What you see:

• List of all branches in your project

• Current branch highlighted

• Quick actions for each branch

Deleting Branches

Remove branches you no longer need.

How to delete:

1. Open the Branches panel

2. Find the branch you want to delete

3. Click the delete icon

4. Confirm deletion

When to delete:

• Experiment didn't work out

• Feature completed and changes moved to main

• Cleaning up old test branches

• Reducing clutter

Can't Delete Current Branch
If you cannot delete the branch you're currently working in, switch to a different branch first, then delete the one you want to remove.

When to Use Branches

Branches are perfect for specific scenarios. Here's when branching makes the most sense.

Testing Design Variations

Try multiple approaches to the same problem.

Example workflow:

Main branch: Current homepage design

Create branches:

• homepage-hero-v1: Traditional hero section

• homepage-hero-v2: Video background hero

• homepage-hero-v3: Animated illustration hero

Result: Compare all three, choose the best, implement in main

A/B Testing Ideas

Build different versions to test with users or stakeholders.

Example workflow:

Main: Pricing page v1

Branch: pricing-simplified

• Remove features comparison table

• Focus on three clear tiers

• Bigger CTAs

Branch: pricing-detailed

• Add detailed feature breakdown

• Include FAQ section

• Add testimonials

Result: Test both versions, use data to decide

Collaborating on Features

Multiple people work on the same feature from different angles.

Example workflow:

Main: Dashboard v1

Team member A: dashboard-charts

• Adds data visualization

Team member B: dashboard-filters

• Adds filtering system

Team member C: dashboard-mobile

• Optimizes for mobile

Result: Review all three, combine best elements

Safe Experimentation

Try bold changes without risk.

Example workflow:

Main: Current stable design

Branch: dark-mode-experiment

• Complete dark mode implementation

• New color palette

• Redesigned components

Result: If successful, move to main. If not, delete branch.

Saving Progress Checkpoints

Create branches at major milestones.

Example workflow:

Main: Active development

Branch: v1-complete

• Save state when v1 finished

Branch: pre-redesign

• Save state before major changes

Result: Always have stable versions to return to

Branch Workflows

Common patterns for using branches effectively.

The Experiment Pattern

Steps:

1. Start on main branch

2. Create experimental branch

3. Try changes without fear

4. If it works → manually implement in main

5. If it doesn't → delete branch

Best for: Bold ideas, major changes, risky experiments

The Variation Pattern

Steps:

1. Start on main branch

2. Create multiple branches (v1, v2, v3)

3. Build different approaches in each

4. Compare results side-by-side

5. Choose winner → implement in main

6. Delete other branches

Best for: Design decisions, A/B tests, comparing approaches

The Collaboration Pattern

Steps:

1. Start on main branch

2. Team members create feature branches

3. Everyone works independently

4. Review all branches together

5. Decide on final approach

6. Manually combine best elements in main

Best for: Team projects, parallel development, feature exploration

The Checkpoint Pattern

Steps:

1. Working on main branch

2. Reach a stable state

3. Create branch as checkpoint (e.g., "stable-v1")

4. Continue working on main

5. If things go wrong → switch to checkpoint branch

6. Start fresh from that stable point

Best for: Major milestones, before big changes, safety nets

Branch Best Practices

Naming Branches

Use clear, descriptive names that explain the branch purpose.

Good naming:

• hero-video-background

• mobile-nav-redesign

• pricing-page-v2

• dark-mode-experiment

• checkout-flow-simplified

Bad naming:

• test

• branch1

• new

• temp

• stuff

When to Create Branches

Create branches for:

• Trying new design directions

• Testing variations

• Collaborating on features

• Safe experimentation

• Major changes

Don't create branches for:

• Small tweaks (use restore points instead)

• Quick fixes (just edit main)

• Minor styling changes

Keeping Branches Organized

Good practices:

• Delete branches when done

• Name branches clearly

• Don't create too many at once

• Review and clean up regularly

• Document what each branch is testing

Working Across Branches

Remember:

• Each branch has independent checkpoints

• Changes don't transfer between branches

• Switch branches to compare results

• Can't merge automatically (yet)

Common Questions

Can I merge branches?

Not yet. Merging functionality is in development. For now, manually implement changes from experimental branches into your main branch.

What happens to checkpoints when I branch?

Each branch has independent checkpoints. The new branch starts with no checkpoints - they're created as you work in that branch.

Can I switch branches while AI is working?

Yes, however we recommend waiting for AI to finish before branching.

Do branches affect my project files?

Each branch represents a different state of your files. Switching branches loads that branch's version of the files.

How many branches can I create?

There's no hard limit, but keep your branch list manageable. Delete branches you're no longer using.

Can team members work on different branches?

Yes. Multiple people can work on different branches simultaneously. This is perfect for parallel exploration and collaboration.