Skip to main content

​
vers branch

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

​
Synopsis

vers branch                          # Create VM from current HEAD
vers branch <vm-id|alias>            # Create VM from specific VM
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. This allows you to continue from exactly where the parent VM left off, but in a separate environment where you can make different changes. The new VM gets an exact copy of the parent’s filesystem and memory 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

  1. State Inheritance: The new VM gets an exact copy of the parent’s filesystem and memory
  2. VM Creation: A new VM is created via the API with a unique VM ID
  3. Optional Aliasing: If --alias is provided, the VM gets a friendly name
  4. Optional Checkout: If --checkout is used, your HEAD pointer switches to the new VM

​
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

​
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 make it easier to remember and switch between VMs
  • Use --checkout when you want to immediately start working on the new VM
  • The parent VM remains unchanged and accessible

​
See Also