Convco

A Conventional commit cli.

Documentation: https://convco.github.io.

convco gives tools to work with Conventional Commits.

It provides the following commands:

• convco changelog: Create a changelog file.
• convco check: Checks if a range of commits is following the convention.
• convco commit: Helps to make conventional commits.
• convco version: Finds out the current or next version.
• convco config: Prints the effective configuration or the default configuration.
• convco completions: Generates tab completions for shells (exists only with the feature completions enabled).

Installation

Convco is built as a single binary. It does not need an additional runtime.

Download release archives from the latest GitHub release:

target=x86_64-unknown-linux-musl
curl -OL "https://github.com/convco/convco/releases/latest/download/convco-${target}.tar.gz"
tar -xzf "convco-${target}.tar.gz" --strip-components=1 "convco-${target}/convco"
sudo install -m 755 convco /usr/local/bin/convco

For macOS or Linux with Homebrew:

brew install convco

With Cargo:

cargo install convco

With Docker:

docker run --rm -v "$PWD:/tmp" -w /tmp convco/convco --help

Building from source

Rust 1.87 or newer is required.

Building with cargo depends on git2 and cmake due to linking with zlib-ng. You can disable the default backend features for a source build:

cargo build --no-default-features

Configuration

convco follows the conventional-changelog-config-spec.

The configuration is loaded in this order:

1. Load the internal defaults.
   • specified in src/conventional/config.rs,
   • see these defaults at convco config --default.
2. If -c or --config is provided, load that file.
3. Otherwise, load ${PWD}/.convco when it exists.
4. Otherwise, load ${PWD}/.versionrc for compatibility with conventional-changelog.

To get the final derived configuration run convco config.

When host, owner and repository are not supplied, convco derives them from the origin git remote. Additional convco-specific config includes commitTemplate, description length limits, initialBumpVersion, and ignoreMessagePattern.

Docker usage

# build the convco image
docker build -t convco .
# run it on any codebase
docker run --rm -v "$PWD:/tmp" -w /tmp convco --help

or use it from the Docker Hub:

docker run --rm -v "$PWD:/tmp" -w /tmp convco/convco --help

or use it from the GitHub Container Registry:

docker run --rm -v "$PWD:/tmp" -w /tmp ghcr.io/convco/convco --help

Use it in .gitlab-ci.yml

If you've created an image and pushed it into your private registry

convco:check:
  stage: test
  image:
    name: convco/convco:latest
  script:
    - check

GitHub Actions

Use convco check in pull requests to validate the commits in the PR range.

name: Pull request
on: [pull_request]

jobs:
  convco:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 10
      - name: Validate commit messages
        shell: bash
        run: |
          set -euo pipefail
          target="x86_64-unknown-linux-musl"
          curl -sSfL "https://github.com/convco/convco/releases/latest/download/convco-${target}.tar.gz" \
            | tar -xz --strip-components=1 "convco-${target}/convco"
          chmod +x convco
          ./convco check ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}

Tools

Changelog

A changelog can be generated using the conventional commits. It is inspired by conventional changelog and the configuration file allows changes to the generated output.

convco changelog > CHANGELOG.md

Limit changelog commits with git pathspecs:

convco changelog --paths 'src,:(exclude)src/generated'
convco changelog --paths src --paths ':(exclude)src/generated'

Check

Check a range of revisions for compliance.

It returns a non-zero exit code if some commits are not conventional. This is useful in a pre-push hook or CI job.

convco check $remote_sha..$local_sha
convco check origin/main..HEAD
git log -1 --format=%B | convco check --from-stdin

Commit

Helps to make conventional commits. A scope, description, body, breaking change and issues will be prompted. Convco will recover the previous message in case git failed to create the commit.

convco commit --feat
convco commit --fix --scope parser --message "handle empty input"
convco commit --feat --breaking --trailer "Reviewed-by: Z"
convco commit --interactive --patch
convco commit --feat -- -p --edit
convco commit --intent-to-add new-file.rs --patch

convco commit can also be used as git core.editor. In this case convco commit will not invoke git commit, but git will invoke convco commit

e.g.:

GIT_EDITOR='convco commit' git commit -p

When persisting the git editor also set sequence.editor when editing the todo list of an interactive rebase.

Or configure a git alias:

git config --global alias.convco '!GIT_EDITOR="convco commit" git commit'

Version

When no options are given it will return the current version. When --bump is provided, the next version will be printed out. Conventional commits are used to calculate the next major, minor or patch. If needed one can provide --major, --minor or --patch to overrule the convention.

convco version --bump

Use --major, --minor or --patch to force the bump, and --prerelease to calculate a prerelease version:

convco version --bump --minor
convco version --bump --prerelease rc

Limit version calculation with git pathspecs:

convco version --bump --paths src
convco version --bump --paths ':(exclude)charts'
convco version --bump --paths 'packages/app,packages/lib'

It is useful to use it with release tools, such as cargo-release:

cargo release $(convco version --bump)

Completions

[!NOTE] This subcommand requires the feature completions to be enabled.

Generates tab completion for the current shell

convco completions

If your shell cannot be detected (the $SHELL variable isn't present) you can specify the shell you want completions generated for.

convco completions bash

The tab completions will be output to stdout so you may want to write them to a file for future use. Here are some example files for given shells:

• Bash: /usr/share/bash-completion/completions/convco
• Zsh: /usr/share/zsh/site-functions/_convco
• Fish: /usr/share/fish/vendor_completions.d/convco.fish
• Elvish: /usr/share/elvish/lib/convco.elv