Two small bits of ergonomics, but they show up everywhere. HEAD is the default target for most commands. Aliases are human-readable names you can use anywhere an id works.
HEAD
HEAD is a pointer to “the VM I’m working on right now.” Most commands default to HEAD when you don’t pass a VM id:
| Command | Default |
|---|
vers connect | Connect to HEAD |
vers execute | Run on HEAD |
vers commit | Commit HEAD |
vers branch | Branch from HEAD |
vers pause / vers resume | Pause/resume HEAD |
vers copy | Transfer to/from HEAD |
vers kill | Delete HEAD |
HEAD is just a pointer, not a live connection. You can have HEAD pointing at one VM while your SSH session is connected to a different VM.
When HEAD moves
HEAD moves automatically when you:
- run
vers run → now points at the new root
- run
vers branch → now points at the new child
- run
vers run-commit → points at the new VM
- run
vers checkout <vm> → explicit move
- delete the VM HEAD points at → HEAD is cleared
Inspecting HEAD
# Print the current HEAD VM id (scripting-friendly)
vers head
# Full status including HEAD
vers status
Where HEAD lives
.vers/HEAD inside your project directory. If you cd into a different project, you get a different HEAD. That’s the whole story — it’s literally a one-line file.
Outside a Vers project, HEAD is undefined and commands that default to it will fail with a clear error. Initialize a project with vers init or pass VM ids explicitly. Aliases
Aliases are human-readable names for VM ids, stored locally. They make the difference between:
vers connect vm-a1b2c3d4e5f6
Creating aliases
When you create a VM:
vers run --vm-alias web-dev
vers branch parent-vm --vm-alias feature-auth
vers run-commit <commit-id> --vm-alias restored
vers alias set web-dev vm-a1b2c3d4
Using aliases
Aliases work anywhere a VM id works:
vers connect web-dev
vers execute web-dev -- ls -la
vers checkout feature-auth
vers branch web-dev --vm-alias hotfix
Inspecting aliases
vers alias # list all
vers alias web-dev # show the id behind an alias
Where they live
~/.vers/aliases.json — a plain JSON map:
{
"web-dev": "vm-a1b2c3d4",
"feature-auth": "vm-ef567890"
}
How HEAD and aliases work together
This is the ergonomics loop Vers wants you to fall into:
Name the VM when you create it
Do work without typing the name
vers connect # implicit HEAD
vers commit # implicit HEAD
vers branch --vm-alias feature # implicit HEAD as source
feature because vers branch sets HEAD.Switch contexts without losing track
vers checkout dev # HEAD back on the parent
vers checkout feature # HEAD back on the branch
See also