Skip to main content

​
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:
  1. Parent Pauses: The source VM is briefly paused for a consistent snapshot
  2. Commit: The source VM’s current state is committed
  3. VM Creation: A new VM is spawned from that commit with a unique VM ID
  4. Parent Resumes: The source VM automatically resumes
  5. Both Run: Both parent and child VMs end up running simultaneously
  6. Optional Aliasing: If --alias is provided, the new VM gets a friendly name
  7. Optional Checkout: If --checkout is used, your HEAD pointer switches to the new VM
When branching from a commit ID:
  1. VM Creation: A new VM is spawned directly from the specified commit
  2. 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

​
See Also