27 releases

0.5.1 Mar 8, 2024
0.5.0 Dec 8, 2023
0.4.3 Oct 3, 2023
0.4.1 Jul 25, 2023
0.1.1 Dec 29, 2019

#30 in Build Utils

Download history 83/week @ 2024-03-11 51/week @ 2024-03-18 39/week @ 2024-03-25 87/week @ 2024-04-01 71/week @ 2024-04-08 38/week @ 2024-04-15 25/week @ 2024-04-22 34/week @ 2024-04-29 47/week @ 2024-05-06 15/week @ 2024-05-13 35/week @ 2024-05-20 25/week @ 2024-05-27 33/week @ 2024-06-03 23/week @ 2024-06-10 53/week @ 2024-06-17 27/week @ 2024-06-24

137 downloads per month

MIT license



GitHub Workflow Status Crates.io

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.


cargo install convco

Building from source

Rust 1.60 or newer is required.

Building with cargo depends on git2 and cmake due to linking with zlib-ng. You can optionally disable this by changing the defaults for a build:

cargo build --no-default-features


convco uses follows the conventional-changelog-config-spec.

The configuration file is loaded in the following order

  1. Load the internal defaults
  2. Then override with values from the command line, convco -c|--config path/to/.convco
  3. Or, if not specified via -c|--config, load ${PWD}/.convco if it exists (or ${PWD}/.versionrc for compatibility with conventional-changelog).

To get the final derived configuration run convco config.

The host: ..., owner: ... and repository: ... when not supplied via custom or the .versionrc are loaded from the git remote origin value.

Docker usage

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

or use it from the Docker Hub:

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

Use it in .gitlab-ci.yml

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

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



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

convco changelog > CHANGELOG.md


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.

convco check $remote_sha..$local_sha


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 can also be used as git core.editor. In this case convco commit will not invoke git commit, but git will invoke convco commit


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'


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

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

cargo release $(convco version --bump)


~593K SLoC