verscout

README

verscout

Find the latest version tag, calculate the next version, print to STDOUT - no tagging, no bumping, no changelog, no publishing.

What is verscout?

verscout is a single binary CLI tool. verscout latest will print the latest version tag of your repository to STDOUT. verscout next will calculate the next version tag based on Conventional Commits, and print it to STDOUT. If no latest or next version exists, verscout will print nothing to STDOUT and exit with code 0 by default.

verscout will not create and push any tags. It will not bump any versions in any files. It will not create a changelog. It will not publish any artifacts.

Why verscout?

I wanted to have a lightweight tool that can tell me the latest and next version based on Git tags and Conventional Commits for use in my CI processes. Most other tools known to me did not fulfill my requirements:

• Print the latest version to STDOUT
• Print the next version to STDOUT
• Print no next version to STDOUT if there are no new commits that should cause a version bump and exit with code 0

Getting Started

Install verscout

Via Homebrew

brew install erNail/tap/verscout

Via mise

mise use -g github:ernail/verscout

Via Binary

Check the releases for the available binaries. Download the correct binary and add it to your $PATH.

Via Go

go install github.com/erNail/verscout

Via Container

docker pull ernail/verscout:<LATEST_GITHUB_RELEASE_VERSION>

From Source

Check out this repository and run the following:

go build

Add the resulting binary to your $PATH.

Run verscout

Get the latest version tag

verscout latest

For verscout to find the latest version, the tags need to be in the format vMAJOR.MINOR.PATCH or MAJOR.MINOR.PATCH

Calculate the next version

verscout next

For verscout to calculate the next version, Conventional Commits need to exist since the latest version tag.

Using the default configuration, fix: will cause a PATCH bump. feat: will cause a MINOR bump. BREAKING CHANGE: in the commit message body or a ! before the : (e.g. feat!:, fix(scope)!:) will cause a MAJOR bump. This behavior can be configured

If no version tags exist, the first version will be 1.0.0 This behavior can also be configured

Configure verscout

To get a complete list of the configuration options, please use the --help or -h flag.

verscout --help

Global options

Working Directory

By default, verscout will run in the current working directory. Use the --dir flag to change this behavior.

verscout --dir ./my-other-repository

Options for verscout latest

Exit Code if no latest version is found

By default, verscout latest will exit with code 0 if no latest version is found due to expected reasons.

The expected reasons are:

• There are no existing tags
• There are no valid version tags

You can change this behavior with the --exit-code flag

verscout latest --exit-code 4

Options for verscout next

Custom Bump Configuration

You can configure which conventional commit keywords cause which kind of bump in a .verscout-config.yaml This is the default configuration used by verscout:

---
bumps:
  majorPatterns:
    - "^\w+(\(.*\))?!:"
    - "(?m)^BREAKING CHANGE:"
  minorPatterns:
    - "^feat(\\(.*\\))?:"
  patchPatterns:
    - "^fix(\\(.*\\))?:"
...

The expressions are evaluated using Go's regexp package.

You can also specify a different file path:

verscout next --config path/to/your/config.yaml

Custom First Version

By default, if no version tags exist, the first version will be 1.0.0. You can configure this behavior:

verscout next --first-version 0.1.0

Be aware that this will have no effect on the keywords and the type of bump they cause. For example, if you want the keyword BREAKING CHANGE: to not cause a bump from 0.1.0 to 1.0.0, you should use a custom bump configuration.

Exit Code if no next version is found

By default, verscout next will exit with code 0 if no next version is found due to expected reasons.

The expected reasons are:

• There are no new commit messages since the last tag
• There are no new commit message since the last tag that use any keywords that will cause a version bump

You can change this behavior with the --exit-code flag

verscout next --exit-code 4

Limitations

• The format of the version tags is currently not configurable
• Bumping any prerelease or release candidate versions is not supported

Planned Features

Please check the open GitHub Issues to get an overview of the planned features.

Development

Install Dependencies

All dependencies can be installed via mise.

mise install

If you are not using mise, check the mise.toml for the required dependencies.

Run Tasks

# Find available tasks
mise tasks

# Run a task
mise run <TASK_NAME>

If you are not using mise, check the mise.toml for the commands.

Documentation

Overview

Package main is the entry point for the verscout application, which handles the initialization and execution of the command line interface.