> ## Documentation Index > Fetch the complete documentation index at: https://docs.vers.sh/llms.txt > Use this file to discover all available pages before exploring further. # Branch # vers branch Create a new VM from an existing VM or commit, inheriting its complete state. ## Synopsis ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers branch # Create VM from current HEAD vers branch # Create VM from specific VM vers branch # Create VM from a specific commit vers branch --alias # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers branch ``` Creates a new VM from your current HEAD VM. ### Create VM from Specific VM ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers branch vm-abc123 ``` Creates a new VM from the specified VM ID or alias. ### Create VM with Custom Alias ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers branch --alias experiment-auth vers branch vm-abc123 --alias backup-state ``` ### `--checkout`, `-c` Automatically switch your HEAD to the new VM after creation: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # Create VM from current HEAD vers branch # Create VM with a descriptive alias vers branch --alias test-environment ``` ### Creating and Switching ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # Create VM and immediately switch to it vers branch --alias experiment --checkout # Your HEAD now points to the new VM ``` ### Creating from Specific VM ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} for i in $(seq 1 10); do vers branch golden-vm --vm-alias "worker-$i" & done wait ``` ### Branch and switch in one step ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers branch main-vm --vm-alias experiment # ...try something... vers kill -y experiment # zero impact on main-vm ``` ## See Also * [vers alias](alias) - View and look up aliases * [vers checkout](checkout) - Switch between VMs * [vers commit](commit) - Create commits manually * [vers status](status) - See your current HEAD and available VMs * [vers run-commit](run-commit) - Start a VM from a commit