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