1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7# formatted-commit
  8
  9[![REUSE status](https://api.reuse.software/badge/git.secluded.site/formatted-commit)](https://api.reuse.software/info/git.secluded.site/formatted-commit)
 10[![Go Report Card](https://goreportcard.com/badge/git.secluded.site/formatted-commit)](https://goreportcard.com/report/git.secluded.site/formatted-commit)
 11
 12CLI tool that produces commits following the Conventional Commits specification
 13through flags, made for LLMs and not really their operators (but I guess you can
 14use this directly if you want). Operators would likely prefer, as the author
 15does, [meteor](https://github.com/stefanlogue/meteor).
 16
 17I've found that LLMs consistently fail to
 18
 19- Format trailers correctly: they add too many newlines between trailers, which
 20  breaks tools like `git interpret-trailers`
 21- Include proper scope notation
 22- Follow the loose 50/72 subject/body standard held by projects like the Linux
 23  kernel. I try to stick to it, but LLMs writing badly-formatted commit messages
 24  means rewording work for me once they're done.
 25
 26`formatted-commit` enforces all of this. Where possible, we "correct" the
 27model's input. Where that's less possible, we error. For example, instead of
 28requiring the model wrap body text at 72 columns, we let it write whatever body
 29it wants and wrap it ourselves. We can't really fix the subject, so
 30`formatted-commit` emits an error when the subject is too long with clear
 31indication of where the 50-character cut-off is.
 32
 33## Installation
 34
 35You need _both_ the binary and the prompt.
 36
 37### The binary
 38
 39- Using [bin](https://github.com/marcosnils/bin) (highly recommended
 40  because it's one tool to manage and update myriad CLI tools
 41  distributed as statically-linked binaries, like _formatted-commit_)
 42  ```bash
 43  bin install goinstall://git.secluded.site/formatted-commit@latest
 44  ```
 45- Using the [go toolchain](https://go.dev/dl) (upgrade with `formatted-commit upgrade`)
 46  ```bash
 47  go install git.secluded.site/formatted-commit@latest
 48  ```
 49
 50### The prompt
 51
 52Paste this snippet into some section of your `~/.config/AGENTS.md` or
 53`~/.claude/CLAUDE.md` or whatever titled something like `## Creating git
 54commits`.
 55
 56```markdown
 57Create/amend commits exclusively using `formatted-commit`. It has no sub-commands and the following options:
 58<formatted-commit_flags>
 59-t --type Commit type (required)
 60-s --scope Commit scope (optional)
 61-B --breaking Mark as breaking change (optional)
 62-m --message Commit message (required)
 63-b --body Commit body (optional)
 64-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
 65-a --add Stage all modified files before committing (optional)
 66--amend Amend the previous commit (optional)
 67-h --help
 68</formatted-commit_flags>
 69<formatted-commit_example>
 70formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Assisted-by: GLM 4.6 via Crush" -b "$(cat <<'EOF'
 71Multi-line
 72
 73- Body
 74- Here
 75
 76EOF
 77)"
 78</formatted-commit_example>
 79```
 80
 81## Contributions
 82
 83Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
 84new account to contribute, you don't need to fork this repo, you don't need to
 85fiddle with `git send-email`, you don't need to faff with your email client to
 86get `git request-pull` working...
 87
 88You just need:
 89
 90- Git
 91- SSH
 92- An SSH key
 93
 94```sh
 95# Clone this repo, make your changes, and commit them
 96# Create a new patch request with
 97git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
 98# After potential feedback, submit a revision to an existing patch request with
 99git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
100# List patch requests
101ssh pr.pico.sh pr ls amolith/llm-projects
102```
103
104See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
105complete example workflow.
106
107[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
108[pr.pico.sh]: https://pr.pico.sh
109
110---
111
112Some other tools if this one interested you
113
114- [_nasin pali_](https://git.secluded.site/np) (`np`) - minimal todo/planning CLI for agents
115- [AgentSh](https://git.secluded.site/agentsh) - press `Ctrl+X` from any shell prompt to message your agent (Crush, Claude Code, etc.)