1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# formatted-commit
8
9[](https://api.reuse.software/info/git.secluded.site/formatted-commit)
10[](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## Changelog
82
83See [CHANGELOG.md](CHANGELOG.md) for release notes and version history.
84(Maintained by [kittylog](https://github.com/cellwebb/kittylog))
85
86## Contributions
87
88Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
89new account to contribute, you don't need to fork this repo, you don't need to
90fiddle with `git send-email`, you don't need to faff with your email client to
91get `git request-pull` working...
92
93You just need:
94
95- Git
96- SSH
97- An SSH key
98
99```sh
100# Clone this repo, make your changes, and commit them
101# Create a new patch request with
102git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
103# After potential feedback, submit a revision to an existing patch request with
104git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
105# List patch requests
106ssh pr.pico.sh pr ls amolith/llm-projects
107```
108
109See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
110complete example workflow.
111
112[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
113[pr.pico.sh]: https://pr.pico.sh
114
115---
116
117Some other tools if this one interested you
118
119- [_nasin pali_](https://git.secluded.site/np) (`np`) - minimal todo/planning CLI for agents
120- [AgentSh](https://git.secluded.site/agentsh) - press `Ctrl+X` from any shell prompt to message your agent (Crush, Claude Code, etc.)