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 tag is Vers’ analogue of git tag: a human-readable name pointing to a commit. Tags are mutable (you can move them with tag update) and cheap (deleting a tag doesn’t touch the commit it points to). vers build -t, vers run-commit, and vers build’s FROM clause all accept tag names anywhere a commit id is expected.

​
Synopsis

vers tag create <name> <commit-id> [-d "description"]
vers tag list                                     # Human-readable
vers tag list -q                                  # Just names
vers tag list --format json                       # Machine-readable
vers tag get <name>
vers tag update <name> --commit <new-commit>      # Move tag
vers tag update <name> --description "..."        # Update description
vers tag delete <name> [<name>...]

​
Subcommands

​
vers tag create

Create a tag pointing to a commit.
Naming rules: alphanumeric characters plus -, _, .; 1–64 characters.
OptionDescription
-d, --descriptionOptional description
vers tag create production abc-123
vers tag create v1.2 abc-123 -d "First stable release"

​
vers tag list

List all tags in your organization.
OptionDescription
-q, --quietJust names, one per line
--format jsonMachine-readable output
vers tag list
vers tag list -q
vers tag list --format json | jq '.[] | {name, commit_id}'

​
vers tag get

Show details for a single tag. 
vers tag get production
vers tag get production --format json

​
vers tag update

Move a tag or update its description. At least one of --commit or --description is required.
OptionDescription
--commitNew commit id to point at
-d, --descriptionNew description
# Promote a newer commit to production
vers tag update production --commit def-456

# Update the description in place
vers tag update production --description "Post-launch hotfix"

​
vers tag delete

Delete one or more tags. Commits they pointed at are unaffected. 
vers tag delete staging
vers tag delete staging preview
vers tag delete $(vers tag list -q)   # nuke all tags

​
Examples

​
Name your build outputs

vers build -t myapp:prod .             # -t calls tag create under the hood
vers run-commit myapp:prod             # Boot the latest prod build

​
Promote through environments

COMMIT=$(vers build -q .)
vers tag create staging "$COMMIT"

# ...testing...

vers tag update production --commit "$COMMIT"

​
Branch off a named tag

vers branch production                 # Branch directly off the tag

​
Common Patterns

​
Tag the latest build

COMMIT=$(vers build -q .)
vers tag update latest --commit "$COMMIT"

​
Promote through environments

COMMIT=$(vers build -q .)
vers tag update staging    --commit "$COMMIT"
# ...after testing...
vers tag update production --commit "$COMMIT"

​
Delete all test tags

vers tag delete $(vers tag list -q | grep '^test-')

​
Pin a release

COMMIT=$(vers commit --format json | jq -r .commit_id)
vers tag create v1.2.0 "$COMMIT" -d "stable release, build $(date -u +%Y-%m-%dT%H:%M:%SZ)"

​
See also