formatted-commit

CLI tool that produces commits following the Conventional Commits specification through flags, made for LLMs and not really their operators (but I guess you can use this directly if you want). Operators would likely prefer, as the author does, meteor.

I've found that LLMs consistently fail to

Format trailers correctly: they add too many newlines between trailers, which breaks tools like git interpret-trailers
Include proper scope notation
Follow the loose 50/72 subject/body standard held by projects like the Linux kernel. I try to stick to it, but LLMs writing badly-formatted commit messages means rewording work for me once they're done.

formatted-commit enforces all of this. Where possible, we "correct" the model's input. Where that's less possible, we error. For example, instead of requiring the model wrap body text at 72 columns, we let it write whatever body it wants and wrap it ourselves. We can't really fix the subject, so formatted-commit emits an error when the subject is too long with clear indication of where the 50-character cut-off is.

Installation

As this is mostly meant for agentic coding tools, you'll need one. I like Crush 💘 (and maintain a fork) or OpenCode as the best more-open options and Amp as the overall best option if you don't mind completely proprietary and paying for 100% of your API usage.

You may install formatted-commit manually using the following command. You may also skip this and just add the prompt snippet; it tells the model about the command so it can try to run it on its own or ask you to run it.

go install git.secluded.site/formatted-commit@latest

Check for upgrades with formatted-commit upgrade, then apply with formatted-commit upgrade -a.

Copy/paste this into wherever you tell your models how to write commits. For Crush, that might be ~/.config/crush/CRUSH.md or ./CRUSH.md in a repo. For my Crush fork and Amp, that's ~/.config/AGENTS.md. Look up where your tool checks for rules files and put this in a section like ## Creating git commits or something.

Create/amend commits exclusively using `formatted-commit`. Try to use it normally, but if it's not in my PATH, ask me to `go install git.secluded.site/formatted-commit@latest`. It has no sub-commands and the following options:
<formatted-commit_flags>
-t --type Commit type (required)
-s --scope Commit scope (optional)
-B --breaking Mark as breaking change (optional)
-m --message Commit message (required)
-b --body Commit body (optional)
-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
-a --amend Amend the previous commit (optional)
-h --help
</formatted-commit_flags>
<formatted-commit_example>
formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Crush <crush@charm.land>" -b "$(cat <<'EOF'
Multi-line

- Body
- Here

EOF
)"
</formatted-commit_example>

Contributions

Patch requests are in amolith/llm-projects on pr.pico.sh. You don't need a new account to contribute, you don't need to fork this repo, you don't need to fiddle with git send-email, you don't need to faff with your email client to get git request-pull working...

You just need:

Git
SSH
An SSH key

# Clone this repo, make your changes, and commit them
# Create a new patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
# After potential feedback, submit a revision to an existing patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
# List patch requests
ssh pr.pico.sh pr ls amolith/llm-projects

See "How do Patch Requests work?" on pr.pico.sh's home page for a more complete example workflow.

Usage

$ formatted-commit -h

  formatted-commit helps you create well-formatted Git commits that follow
  the Conventional Commits specification with proper subject length validation,
  body wrapping, and trailer formatting.

  USAGE

    formatted-commit [command] [--flags]

  EXAMPLES

    # With co-author
    formatted-commit -t feat -m "do a thing" -T "Crush <crush@charm.land>"

    # Breaking change with longer body
    formatted-commit -t feat -m "do a thing that borks a thing" -B -b "$(cat <<'EOF'
    Multi-line
    - Body
    - Here

    This is what borked because of new shiny, this is how migrate
    EOF
    )"

    # Including scope for more precise changes
    formatted-commit -t refactor -s "web/git-bug" -m "fancy shmancy" \
      -b "Had to do a weird thing because..."

    # Check for upgrades
    formatted-commit upgrade

    # Then apply
    formatted-commit upgrade -a

  COMMANDS

    help [command]     Help about any command
    upgrade [--flags]  Check for and apply updates

  FLAGS

    -a --amend         Amend the previous commit (optional)
    -b --body          Commit body (optional)
    -B --breaking      Mark as breaking change (optional)
    -h --help          Help for formatted-commit
    -m --message       Commit message (required)
    -s --scope         Commit scope (optional)
    -T --trailer       Trailer in 'Sentence-case-key: value' format (optional, repeatable)
    -t --type          Commit type (required)
    -v --version       Version for formatted-commit

Clone

README

formatted-commit

Installation

Contributions

Usage