cucco
🐓 An interactive CLI for creating conventional commits
About cucco 🐓
cucco is an interactive CLI for creating conventional commits, built on cocogitto and inspired by cz-cli.
cucco is a fork of koji by Danny Tatom
and Finley Thomalla. It keeps everything koji does and adds git hooks
execution, so that pre-commit and post-commit hooks run exactly as they do
with git commit.
Features
- Create conventional commits with ease
- Run the repository
pre-commitandpost-commithooks, with--no-verifyto skip them - Use alongside cocogitto for automatic versioning, changelog generation, and more
- Use emoji 👋 (or, shortcodes)
- Autocomplete for commit scope, with automatic scope detection from staged files
- Run as a git hook
- Custom commit types
Installation
Linux and macOS
|
The script uses Homebrew when it is available and falls back to downloading
the release binary, verifying its SHA-256 checksum. Pass --version X.Y.Z for
a specific release, --yes to skip the prompt, or set BIN_DIR to change the
install directory (default /usr/local/bin).
Windows
irm https://veeso.github.io/cucco/install.ps1 | iex
Homebrew
Be sure to have git installed first.
Usage
The basic way to use cucco is as a replacement for git commit, enforcing the
conventional commit standard
by writing your commit through an interactive prompt.
# Do some work
# Commit your work
When the short description prompt shows a greyed-out suggestion, press Tab or
the Right arrow to fill it in. You can then edit the text or press Enter to
submit it. Once you have typed something, Tab does nothing and the Right arrow
only moves the cursor. The suggestion is the summary of the last message stored in
.git/COMMIT_EDITMSG, when that message is a conventional commit.
While entering the longer description or breaking-change details, press
Alt+Enter to insert a newline. Press Enter without Alt to submit the prompt.
The characters \n are treated as literal text.
See cucco --help for more options.
Like git commit, cucco can stage changes for you:
# Stage modified and deleted tracked files, like `git commit -a`
# Stage everything, untracked files included, like `git add -A`
-a/--all never stages untracked files. -A/--add-all stages them, but
not ignored files. The two flags cannot be combined, and neither can be used
with --hook or --stdout.
Use cucco completions <SHELL> to generate completion scripts for your shell.
Git hooks
When you commit with cucco, the repository's pre-commit and post-commit
hooks run around the commit, mirroring git commit behavior. If a
pre-commit hook exits non-zero, the commit is aborted. A failing
post-commit hook is reported as a warning and does not abort, matching
git commit.
Pass --no-verify to bypass both hooks:
When --all or --add-all is set, cucco stages the changes before
pre-commit runs, regardless of whether hooks are enabled.
Using as a git hook
An alternative way to use cucco is as a
git hook, running
it any time you run git commit.
Manually
Update .git/hooks/prepare-commit-msg with the following code:
#!/bin/bash
&& ||
husky
prek / pre-commit
Add the prepare-commit-msg hook type and the cucco hook to
.pre-commit-config.yaml:
default_install_hook_types:
repos:
- repo: local
hooks:
- id: prepare-msg
name: prepare commit message
entry: bash -c "exec < /dev/tty && cucco --hook || true"
language: system
stages:
Similar should work for any hook runner, just make sure you're using it with
the prepare-commit-msg hook.
When using it as a hook, any message passed to git commit -m will be used for
the commit summary. Writing your commit as a conventional commit, e.g.
git commit -m "feat(space): delete some stars", will bypass cucco altogether.
Configuration
Config values are prioritized in the following order:
- Passed in as arguments (see:
cucco --help) - Read from file passed in via
--config .cucco.tomlin the working directory- Unix/Redox:
$XDG_CONFIG_HOME/cucco/config.toml~/.config/cucco/config.toml
- Windows:
%USERPROFILE%\AppData\Roaming\cucco\config.toml
- The default config
Options
autocomplete
- Type:
bool - Optional:
true - Description: Enables auto-complete for scope prompt via scanning commit history.
= true
breaking_changes
- Type:
bool - Optional:
true - Description: Enables breaking change prompt.
= true
commit_types
- Type:
Vec<CommitType> - Optional:
true - Description: A list of commit types to use instead of the default.
[[]]
= "feat"
= "✨"
= "A new feature"
emoji
- Type:
bool - Optional:
true - Description: Prepend the commit summary with relevant emoji based on commit type.
= true
issues
- Type:
bool - Optional:
true - Description: Enables issue prompt, which will append a reference to an issue in the commit body.
= true
sign
- Type:
bool - Optional:
true - Description: Sign the commit using the user's GPG key, if one is configured.
= true
force_config_scopes
- Type:
bool - Optional:
true - Description: When
true, the scope prompt becomes a selection list restricted to the configuredcommit_scopes. If a single scope is auto-detected from staged changes it is pre-selected automatically.
= true
allow_empty_scope
- Type:
bool - Optional:
true - Description: When
false, a scope is required and cannot be left blank. Pressing<esc>without a detected scope will abort the commit. Defaults totrue.
= false
commit_scopes
- Type:
Vec<CommitScope> - Optional:
true - Description: A list of named commit scopes. Each scope can carry a human-readable
description(for CLI use), pathpatternsfor automatic detection, and anast_greprule for content-based detection.
For automatically assigning scopes based on the context of the change
[[]]
= "core"
= "Changes to the core library"
= "/crates/core/**/*.rs"
[[]]
= "build"
= ["^/build\\.rs$", "/justfile"]
[[]]
= "test"
= "Test-only changes"
= "/tests/**"
# In reference the above scope \/ (TOML is weird)
[]
= "Rust"
= ["**/*.rs"]
= { = "function_item", = { = "end", = "#[test]" } }
patterns -- one or more regex strings matched against staged file paths
(prefixed with /).
ast_grep -- an ast-grep rule. When any
staged file matches both the files filter and the structural rule, this scope
is pre-assigned. Requires the ast-grep feature (included by default).
As a warning: the rule is read from the staged blob only, so renamed and
deleted paths are matched against their pre-change content.
Development
Every task runs through a just recipe. Run just to
list them. just check is the local quality gate (formatting, Clippy with
warnings denied, rustdoc, cargo-deny and the test suite). Install the tracked
git hooks with just setup_githooks. See CONTRIBUTING.md
and AGENTS.md.
Credits
cucco is a fork of koji, created by Danny Tatom and maintained by Finley Thomalla, released under the MIT license. The original copyright notices are preserved in LICENSE. Thanks to the koji contributors for the foundation this project builds on.
License
Licensed under the MIT license. See LICENSE.