cocogitto/cocogitto: a Rust toolbox that turns Conventional Commits into versions and changelogs

Scoped to one convention, and explicit about it

Cocogitto is a CLI and GitOps toolbox for the Conventional Commits and Semver specifications, written in Rust. The project's own framing is unusually disciplined, because the README has a section titled Non goals, and it lists what the tool will not do.

The first is being a git replacement. The stated position is that it uses some of libgit2 but only to provide features related to the Conventional Commits specification, and that anything else shall be done with git. The second is supporting other commit conventions or git workflows.

That boundary is the design, not a disclaimer. Cocogitto does not care how you branch, how you review, how you stage, or how you rewrite history. It cares about one thing: given a history written in a specific format, what version is that history, and what should the changelog say. The stated goals follow from that, namely making the specification easy, letting people focus on work instead of correcting small mistakes and typos, enforcing correctness about Semver and Conventional Commits, and automating things such as version bumping.

The tool set that follows is correspondingly narrow. The features list covers verified commits, automatic version bump and changelog generation with your own custom steps and workflows, release profiles for branching models that need different steps for releases, pre-releases and hotfixes, conventional git log search by scope and commit type, GitHub integration through an action and a bot to enforce the specification, and monorepo support for automatic versioning.

cog commit makes the format the easy path

Creating a compliant commit is the first thing a developer touches, and the command is designed to be faster than typing the format by hand:

# With cog
cog commit feat "add awesome feature"

# With git
git commit -m "feat: add awesome feature"

The comparison in the documentation is the point. The tool exists so that the conventional format is the path of least resistance rather than something you correct afterwards.

The `cog commit` command has subcommands for the default `fix` and `feat` Conventional Commits types, plus the Angular commit conventional commit types, which the documentation links to Angular's own contributing guidelines. That last part is a real convenience for teams migrating from an Angular style, since the type names are already agreed on and the subcommand is already there rather than something to add to a hook script.

The conventional git log view goes the other way. The features list describes a conventional git log that searches your commit history matching Conventional Commits items such as scope and commit type, which is the view you need when you want to know what touched a particular area without writing a filter yourself.

cog bump runs five steps and calls your hooks

The bump command is where the tool earns its place, and the documentation describes it as a five step sequence. It determines a version number according to your commit history, performs the configuration defined pre-bump commands, appends the version's changelog to your repository changelog file, creates a version commit and tags it, and performs post-bump commands.

Everything you need to change is in a `cog.toml` file at the repository root, and the hooks run arbitrary commands with the computed version available to them:

# File: cog.toml
pre_bump_hooks = [
    "echo {{version}}",
]


post_bump_hooks = [
    "git push",
    "git push origin {{version}}",
]

[changelog]
path = "CHANGELOG.md"
template = "remote"
remote = "github.com"
repository = "cocogitto_bot_playground"
owner = "cocogitto"
authors = [
  { username = "oknozor", signature = "Paul Delafosse"}
]

The `{{version}}` placeholder is the seam that makes the tool composable. A pre-bump hook can write the new version into a manifest, and a post-bump hook can push the commit and the tag, which is what the example does. The `[changelog]` table controls where the changelog lives, which template renders it, and, for the `remote` template, which repository and owner the links point at.

Release profiles are the answer to branching models that need different steps for a release, a pre-release or a hotfix, so a team with a `release/` branch and a `hotfix/` branch can attach different hooks to each situation rather than writing one script that branches on the current branch name. Monorepo support, described as automatic versioning for monorepositories out of the box, covers the other common shape.

Changelogs rendered from tera templates

`cog changelog` generates markdown changelogs using tera templates, with several built-in templates and the option to define your own. The output in the documentation shows the shape of the default result, and it is worth reading closely because it determines how much editing your changelog needs afterwards.

The example groups entries under headings that follow the commit type, such as Bug Fixes, Features, Miscellaneous Chores, Refactoring and Tests. Each entry carries a scope in parentheses when the commit had one, a short hash, and the author. The author can be rendered as a plain name or in italics, and the changelog configuration lets you map a GitHub username to a display signature, which is how a project keeps a stable name in the changelog when someone's account or display name changes.

Because the template engine is tera, the same machinery that renders the built-in templates renders your own, so the format of the changelog is not fixed by the project. A team that wants a different grouping, or a customer facing summary instead of raw commit messages, writes a template rather than editing generated Markdown by hand after every release.

The `cog changelog` command takes no arguments in the documented example, and the rendering pipeline is defined entirely in configuration.

One binary, one system dependency, libgit2 underneath

The dependency claim is specific: Cocogitto has one standalone binary, and the only system dependency is libgit2. That is what makes the release story simple, and it is visible in the workspace manifest, where the `git2` crate at version 0.20.0 is the bridge to that library.

The rest of the dependency list describes the feature set. `clap` with the derive feature is the command line parser, and `clap_complete` and `clap_mangen` generate shell completions and a man page, which is a sign that the tool is expected to be used from a shell every day. `tera` is the template engine for changelogs, `conventional_commit_parser` at 0.9.4 does the actual commit parsing, and `pest` and `pest_derive` provide a parser generator for the more involved grammars. `semver` handles version comparison, `petgraph` provides a graph structure, `serde-xml-rs` appears for XML handling, and `globset` and `shell-words` deal with patterns and command strings. `cog_schemars` exists to generate a JSON schema for the configuration, which is what lets an editor validate your `cog.toml`.

The build settings are tuned for a distributable binary rather than for a library. The release profile sets `opt-level = 2`, `lto = "fat"`, `codegen-units = 1` and `panic = "abort"`, and the workspace requires Rust 1.78.0 on edition 2021.

Cross compiled releases and a container image

The `justfile` in the repository shows how the binaries are produced, and it targets three architectures: x86_64 with the musl target, armv7 with the musleabihf target, and aarch64 with the gnu target. Each build runs `cross build --target ... --release` and then clears the release target directory, and a `build-all` recipe runs all three. A `docker-build` recipe then uses `docker buildx build` for the `linux/amd64`, `linux/arm/v7` and `linux/arm64/v8` platforms.

The container image is published at `ghcr.io/cocogitto/cog:latest`, and the documented usage is:

docker pull ghcr.io/cocogitto/cog:latest
docker run -t -v "$(pwd)":/app/ check

The note that accompanies it is the part that trips people up: you need to mount a volume pointing at your target directory for `cog` to be able to operate on your git log. The tool reads history, so it needs the repository, and a container without the mount sees an empty directory.

The `justfile` also carries profiling recipes, one using `perf record` with `inferno-collapse-perf` to render a flamegraph, and another running `valgrind --tool=massif` over `cog changelog`. That level of tooling for a changelog command suggests the maintainers treat generation speed as something worth measuring.

For installation, the README lists package manager routes for Arch Linux, NixOS, Void Linux and macOS, and the Cargo route for everyone else:

cargo install --locked cocogitto

The `--locked` flag is the one to keep, since it installs the versions recorded in the project's own `Cargo.lock`.

What the tool will not do, and what changed in 7.0.0

The wrong-tool cases follow directly from the non-goals, and they are worth being blunt about. A team that writes commit messages in a house style, or that uses a ticket prefix and no type at all, gains nothing from the automated version computation, because the version is derived from commit types. A team that wants a general purpose changelog generator across several repositories with different conventions is looking at the wrong tool, since the project states that supporting other commit conventions is a non-goal.

The second wrong case is expecting Cocogitto to be the release pipeline. It computes a version, writes a changelog, makes a commit and a tag, and runs the hooks you give it. Publishing, signing artefacts, creating a GitHub release and deploying are all things you either do in a hook or do not do, and the hook mechanism is deliberately a thin seam rather than a pipeline engine.

On versions, the release history is worth reading before you pin. Version 6.4.0 was published on 2025-10-18, 6.5.0 on 2025-11-02, and 7.0.0 on 2026-03-04, a jump to a new major version, and the last push to the repository was on 2026-04-22. The repository is not archived and the project ships a `CHANGELOG.md` of its own, which is the place to look before moving a team from one major to the next. The licence is MIT, so embedding the tool in a build or shipping it with your own tooling carries no copyleft obligation.

Editorial conclusion

Adopt Cocogitto if your team already writes Conventional Commits and wants the version bump, the changelog and the release commit to be derived from that history rather than maintained by hand, since the bump step is exactly where mistakes happen. Do not adopt it for a team whose commit convention is something else, because the project states plainly that it is not intended for any context other than Conventional Commits and Semver, and do not treat it as a git replacement, since it uses libgit2 only for the features that convention needs. Verify first that your changelog template and remote repository settings in `cog.toml` match where you actually publish, that your pre-bump and post-bump hooks are idempotent, since a bump that fails halfway leaves a tag behind, and that the version you install matches the documented behaviour of the 7.0.0 release.

Frequently asked questions

Official sources

1. cocogitto/cocogitto on GitHub
2. License: MIT
3. Project website
4. README
5. Releases