Skip to content

README.md

Latest commit

 

History

History
260 lines (180 loc) · 8.28 KB

README.md

File metadata and controls

260 lines (180 loc) · 8.28 KB

Committy

🚀 Generate clear, concise, and structured commit messages effortlessly with Committy!

🌟 Features

  • Generate commit messages compatible with SemVer specification
  • Support for various commit types (feat, fix, build, etc.)
  • Option to indicate breaking changes
  • Short and long commit message support
  • Amend existing commits
  • Easy-to-use CLI interface

🤔 Why Committy?

Committy was born out of the need for a simple, efficient tool to generate structured commit messages. Whether you're working on a personal project or collaborating with a team, Committy helps you:

  • Maintain a clean and consistent commit history
  • Easily generate changelogs
  • Adhere to commit message best practices
  • Save time on writing detailed commit messages

Plus, it's a great way to learn and practice Rust programming!

🚀 Quick Start

Installation

curl -fsSL https://raw.githubusercontent.com/martient/committy/refs/heads/main/install.sh | bash

Basic Usage

To generate a commit message:

committy

Demo

Commit demo

📚 Documentation

  • Full docs live in docs/ (Astro + Starlight): docs/src/content/docs/
  • Key references:
    • Agent Workflows: docs/src/content/docs/reference/agent-workflows.mdx
  • Group Commit: docs/src/content/docs/reference/group-commit.mdx
  • AI Flags & Security: docs/src/content/docs/reference/ai-flags.mdx
  • Troubleshooting: docs/src/content/docs/reference/troubleshooting.mdx
  • CLI Workflow Reference: docs/CLI_WORKFLOW_REFERENCE.md
  • Command Surface Overview: docs/COMMAND_SURFACE.md

🛠 Options and Commands

Amend an existing commit

committy amend

# Non-interactive amend preview
committy --non-interactive amend --type fix --message "adjust release note wording" --dry-run --output json

# The same amend flow also works through commit flags
committy --non-interactive commit --amend --type fix --message "adjust release note wording" --dry-run --output json

Demo

Amend demo

Create a short commit

committy --non-interactive commit --type chore --message "change the api version"

Create a short commit and amend

committy --non-interactive amend --type chore --message "change the api version"

Git and SSH overrides

Committy uses native git by default. When you need a repo-specific SSH transport or signing setup, pass one or more --git-config key=value overrides:

committy --non-interactive commit \
  --type feat \
  --message "use alternate ssh identity" \
  --git-config 'core.sshCommand=ssh -i ~/.ssh/customer_key -o IdentitiesOnly=yes'

committy --non-interactive tag --name v1.2.3 \
  --git-config 'gpg.format=ssh' \
  --git-config "user.signingkey=$HOME/.ssh/signing_key.pub"

You can also persist those overrides in user config (~/.config/committy/config.toml) or repo config (.committy/config.toml):

[git]
config_overrides = [
  "core.sshCommand=ssh -i ~/.ssh/customer_key -o IdentitiesOnly=yes"
]

Expanded command surface

Committy includes native release, changelog, version, and convention-introspection commands:

committy bump --dry-run --output json
committy changelog --dry-run --output json
committy version --project --output json
committy schema --output json
committy example --output json
committy info --output json
committy ls --output json
committy config scaffold --dry-run --output json

See docs/COMMAND_SURFACE.md for the command overview and docs/CLI_WORKFLOW_REFERENCE.md for provider-specific examples.

⚙️ CLI Reference & Advanced Usage

Output format

  • Use --output json|text on commands that support it.
  • branch --dry-run --output json returns a machine-readable branch plan.
  • commit --dry-run --output json returns the resolved commit message and workflow preview.
  • lint --output json prints { ok, count, issues }.
  • tag --output json (with --dry-run) prints { ok, new_tag }.
  • --repo-path lets agents target another checkout without changing cwd.

Verbosity

  • -v or --verbose: increase log verbosity. Repeat for more details (-vv).
  • -q or --quiet: only error logs.
  • Defaults to info when neither is provided.

Non-interactive mode

  • --non-interactive disables prompts (ideal for CI).
  • Also enabled when COMMITTY_NONINTERACTIVE=1 or CI=1.

Fetch control for tags

  • --fetch / --no-fetch controls whether tags are fetched from remote before calculation.
  • Default: fetch is enabled unless --no-fetch is provided.
  • Remote publishing is explicit: use --publish --confirm-publish to push tags or version-bump commits.
  • Example (no remote access):
committy --non-interactive tag --no-fetch --dry-run --not-publish --output json

Agent-friendly preview flow

  • Preview first, then apply:
    • committy --non-interactive branch --type feat --ticket AI42 --subject "agent flow" --dry-run --output json
    • committy --non-interactive commit --type feat --message "add agent flow" --dry-run --output json
    • committy --non-interactive group-commit --mode plan --output json
  • Remote mutations require confirmation:
    • committy --non-interactive group-commit --mode apply --push --confirm-push --output json
    • committy --non-interactive tag --publish --confirm-publish --output json

Stable lint exit codes (for CI)

  • 0 = OK, no issues
  • 3 = Lint issues found
  • 1 = Error

Example:

committy --non-interactive lint --repo-path . --output json || {
  code=$?; if [ $code -eq 3 ]; then echo "Lint issues"; else exit $code; fi
}

Native git verification

  • For signed commit/tag and SSH identity smoke testing, run ./scripts/verify_native_git_e2e.sh.
  • The harness is documented in docs/NATIVE_GIT_E2E.md and can also be triggered from the manual GitHub Actions workflow Native Git Verification.

Configurable version bump rules

Committy determines semantic version bumps using regex patterns loaded from config.toml.

  • Default location: ~/.config/committy/config.toml
  • Override directory with COMMITTY_CONFIG_DIR (the file must be named config.toml).
  • Keys:
    • major_regex
    • minor_regex
    • patch_regex

Example config.toml (use single quotes for literal regex):

minor_regex = '(?im)^fix(?:\s*\([^)]*\))?:'
patch_regex = '(?im)^docs(?:\s*\([^)]*\))?:'
major_regex = '(?im)^(breaking change:|feat(?:\s*\([^)]*\))?!:)'

This example treats fix: commits as a minor bump (instead of patch) and moves docs: to patch.

📝 Commit Types

Committy supports the following commit types:

  • feat: New feature
  • fix: Bug fix
  • build: Changes that affect the build system or external dependencies
  • chore: Other changes that don't modify src or test files
  • ci: Changes to CI configuration files and scripts
  • cd: Changes to CD configuration files and scripts
  • docs: Documentation only changes
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • revert: Revert a previous commit
  • style: Changes that do not affect the meaning of the code
  • test: Adding missing tests or correcting existing tests

💥 Breaking Changes

When prompted, you can indicate if your commit includes breaking changes. This will add a ! at the end of the commit type, signaling a breaking change as per conventional commit standards.

📄 Commit Message Structure

Short Commit Message

A brief, concise summary of the changes (around 150 characters). Think of it as a TL;DR for your commit.

Long Commit Message

A more detailed explanation of the changes, which will be included in the changelog. Use this to provide context, reasoning, and any other relevant information about your changes.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create a new branch for your feature or bug fix
  3. Make your changes and commit them
  4. Push your changes to your forked repository
  5. Create a pull request to the 'develop' branch of the main repository

Please see the CONTRIBUTING file for more details.

📜 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🙏 Acknowledgments

  • Inspired by the need for consistent commit messages
  • Built with love using Rust 🦀