vers head prints the VM ID that HEAD currently points to. It’s the scripting primitive behind the default target for most other commands — when you run vers status or vers commit without an argument, HEAD is what they resolve to.
Synopsis
Prints the HEAD VM ID to stdout, or fails with a non-zero exit code if there is no HEAD.
Examples
Use HEAD in a script
VM=$(vers head)
echo "Working on $VM"
vers execute "$VM" -- uptime
Chain with other commands
# Info for HEAD
vers info $(vers head)
# Kill HEAD explicitly
vers kill $(vers head)
Most commands already default to HEAD when no VM is given. Use vers head when you need the ID as a value — in a variable, a label, or a pipeline into a non-Vers tool.
How HEAD works
HEAD is a per-project pointer stored in .vers/HEAD. It moves automatically when you:
- run
vers run (points at the new root VM)
- run
vers branch (points at the new branch)
- run
vers checkout <vm> (explicit move)
- delete the HEAD VM (cleared)
If you’re not inside a Vers project directory, or HEAD hasn’t been set, the command fails.
Common Patterns
Check whether you’re in a Vers project
if vers head >/dev/null 2>&1; then
echo "HEAD is $(vers head)"
else
echo "not in a Vers project, or HEAD not set"
fi
Use HEAD in your shell prompt
# in ~/.bashrc / ~/.zshrc
PS1='[vers:$(vers head 2>/dev/null || echo "-")] \w $ '
Pipe into any VM-taking command
vers info $(vers head)
vers execute $(vers head) -- uptime
ssh $(vers head).vm.vers.sh
See also