versions

CLI to flexibly increment a project's version

Usage

To increment patch version of current project:

npx versions patch

Options

usage: versions [options] patch|minor|major|prerelease [files...]

  Options:
    -a, --all             Add all changed files to the commit
    -b, --base <version>  Base version. Default is from latest git tag or 0.0.0
    -p, --prefix          Prefix version string with a "v" character. Default is none
    -c, --command <cmd>   Run command after files are updated but before git commit and tag
    -d, --date [<date>]   Replace dates in format YYYY-MM-DD with current or given date
    -i, --preid <id>      Prerelease identifier, e.g., alpha, beta, rc
    -m, --message <str>   Custom tag and commit message
    -r, --replace <str>   Additional replacements in the format "s#regexp#replacement#flags"
    -g, --gitless         Do not perform any git action like creating commit and tag
    -D, --dry             Do not create a tag or commit, just print what would be done
    -R, --release         Create a GitHub or Gitea release with the changelog as body
    -v, --version         Print the version
    -h, --help            Print this help

  The message and replacement strings accept tokens _VER_, _MAJOR_, _MINOR_, _PATCH_.

  Examples:
    $ versions patch
    $ versions prerelease --preid=alpha
    $ versions -c 'npm run build' -m 'Release _VER_' minor file.css

Signing commits and tags

To automatically sign commits and tags created by versions with GPG add this to your ~/.gitconfig:

[user]
  signingkey = <keyid>
[commit]
  gpgSign = true
[tag]
  forceSignAnnotated = true
[push]
  gpgSign = if-asked

Creating releases

When using the --release option, versions will automatically create a GitHub or Gitea release after creating the tag. The release body will contain the same changelog as the commit message.

The tool will automatically detect whether you're using GitHub or Gitea based on your git remote URL.

API Tokens

For GitHub releases, provide an API token via one of these environment variables (in priority order):

• VERSIONS_FORGE_TOKEN
• GITHUB_API_TOKEN
• GITHUB_TOKEN
• GH_TOKEN
• HOMEBREW_GITHUB_API_TOKEN

For Gitea releases, provide an API token via one of these environment variables (in priority order):

• VERSIONS_FORGE_TOKEN
• GITEA_API_TOKEN
• GITEA_AUTH_TOKEN
• GITEA_TOKEN

Example:

export GITHUB_TOKEN=ghp_your_token_here
versions --release patch

CI environments

CI environments usually do incomplete git checkouts without tags. Fetch tags first:

git fetch --tags --force

© silverwind, distributed under BSD licence