vers branch

Create a new VM from an existing VM or commit, inheriting its complete state.

Synopsis

vers branch                          # Create VM from current HEAD
vers branch <vm-id|alias>            # Create VM from specific VM
vers branch <commit-id>              # Create VM from a specific commit
vers branch --alias <alias-name>     # Create VM with custom alias
vers branch --checkout               # Create and switch to new VM

Description

The branch command creates a new VM that inherits the complete state from an existing VM or commit. This allows you to continue from exactly where the source left off, but in a separate environment where you can make different changes. When branching from a running VM, the parent is briefly paused to create a consistent snapshot, then a new VM spawns from that commit and the parent automatically resumes. Both VMs end up running simultaneously. When branching from a commit ID, the new VM is created directly from that saved state.

Basic Usage

Create VM from Current HEAD

vers branch

Creates a new VM from your current HEAD VM.

Create VM from Specific VM

vers branch vm-abc123

Creates a new VM from the specified VM ID or alias.

Create VM with Custom Alias

vers branch --alias feature-test

Creates a new VM with a custom alias instead of just using the VM ID.

Options

`--alias`, `-n`

Assign a custom alias to the new VM:

vers branch --alias experiment-auth
vers branch vm-abc123 --alias backup-state

`--checkout`, `-c`

Automatically switch your HEAD to the new VM after creation:

vers branch --checkout --alias new-feature
# Creates the VM and switches your HEAD to it

What Happens When You Branch

When branching from a VM:

Parent Pauses: The source VM is briefly paused for a consistent snapshot
Commit: The source VM’s current state is committed
VM Creation: A new VM is spawned from that commit with a unique VM ID
Parent Resumes: The source VM automatically resumes
Both Run: Both parent and child VMs end up running simultaneously
Optional Aliasing: If --alias is provided, the new VM gets a friendly name
Optional Checkout: If --checkout is used, your HEAD pointer switches to the new VM

When branching from a commit ID:

VM Creation: A new VM is spawned directly from the specified commit
Optional Aliasing/Checkout: Same as above

Examples

Basic VM Creation

# Create VM from current HEAD
vers branch

# Create VM with a descriptive alias
vers branch --alias test-environment

Creating and Switching

# Create VM and immediately switch to it
vers branch --alias experiment --checkout

# Your HEAD now points to the new VM

Creating from Specific VM

# Create from a specific VM by ID
vers branch vm-abc123 --alias backup

# Create from a VM by alias
vers branch main-vm --alias feature-branch

Creating from a Commit

# Create from a specific commit (useful for restoring previous states)
vers branch c123456789abcdef --alias restored-state

The commit ID is automatically detected - if the ID doesn’t match an existing VM, it’s treated as a commit ID.

Understanding Branch Output

When you create a VM, you’ll see output like:

Using current HEAD VM: vm-abc123
Creating new VM from: vm-abc123
✓ New VM created successfully!

New VM details:
VM ID: vm-def456
Alias: test-environment
State: Running

Use --checkout or -c to switch to the new VM
Run 'vers checkout test-environment' to switch to this VM

This shows:

Which VM was used as the source
The new VM’s ID and alias (if provided)
The current state of the new VM
Instructions for switching to the new VM

Common Workflows

Experimentation

# Create a copy of your current state for testing
vers branch --alias experiment

# Do your testing on the experiment VM
vers checkout experiment
# ... make changes

# Switch back to original
vers checkout main

Parallel Development

# Create multiple VMs for different approaches
vers branch --alias approach-a
vers branch --alias approach-b

# Work on approach A
vers checkout approach-a
# ... work

# Switch to approach B
vers checkout approach-b
# ... work

Tips

If you don’t specify --alias, the new VM will only be accessible by its VM ID
Aliases are stored locally at ~/.vers/aliases.json - they don’t sync between machines
Use --checkout when you want to immediately start working on the new VM
The parent VM remains unchanged and accessible

Common Patterns

Fan out N parallel workers

Branch a prepared VM into N isolated copies — agent swarms, parallel tests, scenario exploration:

for i in $(seq 1 10); do
  vers branch golden-vm --vm-alias "worker-$i" &
done
wait

Branch and switch in one step

vers branch my-vm --vm-alias feature-x --checkout
# HEAD now points at feature-x

Branch from a tag or commit, not a live VM

# Branch off a named tag
vers branch production --vm-alias prod-repro

# Branch off a specific commit
vers branch abc-123 --vm-alias commit-repro

Explore and discard

vers branch main-vm --vm-alias experiment
# ...try something...
vers kill -y experiment    # zero impact on main-vm

Overview

Project Commands

Branch Commands

Repository Commands

VM Commands

Environment

Auth Commands

Utility Commands

Branch

vers branch

Synopsis

Description

Basic Usage

Create VM from Current HEAD

Create VM from Specific VM

Create VM with Custom Alias

Options

`--alias`, `-n`

`--checkout`, `-c`

What Happens When You Branch

Examples

Basic VM Creation

Creating and Switching

Creating from Specific VM

Creating from a Commit

Understanding Branch Output

Common Workflows

Experimentation

Parallel Development

Tips

Common Patterns

Fan out N parallel workers

Branch and switch in one step

Branch from a tag or commit, not a live VM

Explore and discard

See Also

​vers branch

​Synopsis

​Description

​Basic Usage

​Create VM from Current HEAD

​Create VM from Specific VM

​Create VM with Custom Alias

​Options

​--alias, -n

​--checkout, -c

​What Happens When You Branch

​Examples

​Basic VM Creation

​Creating and Switching

​Creating from Specific VM

​Creating from a Commit

​Understanding Branch Output

​Common Workflows

​Experimentation

​Parallel Development

​Tips

​Common Patterns

​Fan out N parallel workers

​Branch and switch in one step

​Branch from a tag or commit, not a live VM

​Explore and discard

​See Also

vers branch

Synopsis

Description

Basic Usage

Create VM from Current HEAD

Create VM from Specific VM

Create VM with Custom Alias

Options

`--alias`, `-n`

`--checkout`, `-c`

What Happens When You Branch

Examples

Basic VM Creation

Creating and Switching

Creating from Specific VM

Creating from a Commit

Understanding Branch Output

Common Workflows

Experimentation

Parallel Development

Tips

Common Patterns

Fan out N parallel workers

Branch and switch in one step

Branch from a tag or commit, not a live VM

Explore and discard

See Also