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 completions: Generates tab completions for shells (exists only with the feature completions enabled).

Installation

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

Configuration

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

The configuration file is loaded in the following order

1. Load the internal defaults
   • specified in src/conventional/config.rs,
   • see these defaults at convco config --default.
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

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

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 the output.

convco changelog > CHANGELOG.md

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.

convco check $remote_sha..$local_sha

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 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

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 outputed to the stdout so you may want to output them to a certain file to save them 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