Skip to main content

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.

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

vers head
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