Skip to main content
A commit is an immutable snapshot of a VM’s full state — filesystem, memory, CPU registers — captured at the moment you ran vers commit. Commits have a content-addressable id (e.g. c123456789abcdef) that uniquely identifies that exact state. Commits are the currency of sharing, reuse, and reproducibility in Vers. Everything that “starts from somewhere” starts from a commit.

​
What a commit captures

In practice: if your work is in memory or on disk, it’s in the commit. If it depends on the outside world, you’ll need to re-establish that.

​
Creating a commit

Committing pauses the VM. Run vers resume afterward if you want to keep working with it.
The output is a commit id. You can pipe it straight into other commands:

​
Restoring from a commit

This boots a fresh VM from the saved state. It doesn’t “resume” the original VM — it creates a new one, identical to the moment of the commit, with its own id and IP. You can restore the same commit any number of times. Each call produces an independent VM.

​
Commits vs branches vs forks

These words get muddled — a quick disambiguation: Branches always produce a running VM. Commits always produce a frozen state. Restores always produce a running VM from a frozen state.

​
Lifetime and deletion

Commits persist until you explicitly delete them with vers commit delete. They survive:
  • The deletion of the VM that produced them
  • The deletion of the child VMs they created
  • Your CLI logging out and back in
This makes commits the right place to stash “I might need this later” state. A VM is ephemeral; a commit is durable.

​
Tagging commits

Commit ids are long and unmemorable. Tags fix that:
Tags are mutable — you can move them with vers tag update — and cheap. Deleting a tag doesn’t touch the commit it pointed at. Anywhere a commit id is accepted (vers run-commit, vers branch, vers build’s FROM), you can pass a tag name instead.

​
Repositories

For structured naming, tags can live inside repositories: my-app:latest, my-app:v1.2, etc. A repo is a namespace for a related group of commits. Repos can be public (other orgs can fork them) or private. See vers repo for the full workflow; most users can get away with plain tags until they need the structure.

​
A typical workflow

1

Prepare

Boot a VM, install dependencies, configure things.
2

Freeze

3

Fan out

Every future VM starts from this known-good base.

​
See also