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## 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## Usage
111
112```text
113$ formatted-commit -h
114
115 formatted-commit helps you create well-formatted Git commits that follow
116 the Conventional Commits specification with proper subject length validation,
117 body wrapping, and trailer formatting.
118
119 USAGE
120
121 formatted-commit [command] [--flags]
122
123 EXAMPLES
124
125 # With Assisted-by
126 formatted-commit -t feat -m "do a thing" -T "Assisted-by: GLM 4.6 via Crush"
127
128 # Breaking change with longer body
129 formatted-commit -t feat -m "do a thing that borks a thing" -B -b "$(cat <<'EOF'
130 Multi-line
131 - Body
132 - Here
133
134 This is what borked because of new shiny, this is how migrate
135 EOF
136 )"
137
138 # Including scope for more precise changes
139 formatted-commit -t refactor -s "web/git-bug" -m "fancy shmancy" \
140 -b "Had to do a weird thing because..."
141
142 # Check for upgrades
143 formatted-commit upgrade
144
145 # Then apply
146 formatted-commit upgrade -a
147
148 COMMANDS
149
150 help [command] Help about any command
151 upgrade [--flags] Check for and apply updates
152
153 FLAGS
154
155 -a --add Stage all modified files before committing (optional)
156 --amend Amend the previous commit (optional)
157 -b --body Commit body (optional)
158 -B --breaking Mark as breaking change (optional)
159 -h --help Help for formatted-commit
160 -m --message Commit message (required)
161 -s --scope Commit scope (optional)
162 -T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
163 -t --type Commit type (required)
164 -v --version Version for formatted-commit
165```