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
11[](https://goreportcard.com/report/git.secluded.site/formatted-commit)
12
13CLI tool that requires conformance with the Conventional Commits specification
14through flags, made for LLMs and not really for the operators (but I guess you
15can use this directly if you want). Operators would likely prefer, as the author
16does, [meteor](https://github.com/stefanlogue/meteor).
17
18`formatted-commit` enforces a 50-character subject limit and sanitises/wraps the body at 72
19characters. I might make that configurable. Idk. It's a loose standard held by
20projects like the Linux kernel and I try to stick to it.
21
22## Installation
23
24As this is mostly meant for agentic coding tools, you'll need one. I like [Crush
25💘](https://github.com/charmbracelet/crush) (and maintain [a
26fork](https://git.secluded.site/crush)) or [OpenCode](https://opencode.ai/) as
27the best more-open options and [Amp](https://ampcode.com/) as the overall best
28option if you don't mind completely proprietary and paying for 100% of your API
29usage.
30
31You may install `formatted-commit` manually using the following command. You may
32also skip this and just add the prompt snippet; it tells the model about the
33command so it can try to run it on its own or ask you to run it.
34
35```bash
36go install git.secluded.site/formatted-commit@latest
37```
38
39Copy/paste this into wherever you tell your models how to write commits. For
40Crush, that might be `~/.config/crush/CRUSH.md` or `./CRUSH.md` in a repo. For
41[my Crush fork](https://git.secluded.site/crush) and Amp, that's
42`~/.config/AGENTS.md`. Look up where your tool checks for rules files and put
43this in a section like `## Creating git commits` or something.
44
45```markdown
46Create/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:
47<formatted-commit_flags>
48-t --type Commit type (required)
49-s --scope Commit scope (optional)
50-B --breaking Mark as breaking change (optional)
51-m --message Commit message (required)
52-b --body Commit body (optional)
53-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
54-a --amend Amend the previous commit (optional)
55-h --help
56</formatted-commit_flags>
57<formatted-commit_example>
58formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Crush <crush@charm.land>" -b "$(cat <<'EOF'
59Multi-line
60
61- Body
62- Here
63
64EOF
65)"
66</formatted-commit_example>
67```
68
69## Contributions
70
71Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
72new account to contribute, you don't need to fork this repo, you don't need to
73fiddle with `git send-email`, you don't need to faff with your email client to
74get `git request-pull` working...
75
76You just need:
77
78- Git
79- SSH
80- An SSH key
81
82```sh
83# Clone this repo, make your changes, and commit them
84# Create a new patch request with
85git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
86# After potential feedback, submit a revision to an existing patch request with
87git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
88# List patch requests
89ssh pr.pico.sh pr ls amolith/llm-projects
90```
91
92See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
93complete example workflow.
94
95[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
96[pr.pico.sh]: https://pr.pico.sh
97
98## Usage
99
100```text
101$ formatted-commit -h
102
103 formatted-commit helps you create well-formatted Git commits that follow
104 the Conventional Commits specification with proper subject length validation,
105 body wrapping, and trailer formatting.
106
107 USAGE
108
109
110 formatted-commit [--flags]
111
112
113 EXAMPLES
114
115
116 # With co-author
117 formatted-commit -t feat -m "do a thing" -T "Crush <crush@charm.land>"
118
119 # Breaking change with longer body
120 formatted-commit -t feat -m "do a thing that borks a thing" -B "$(cat <<'EOF'
121 Multi-line
122 - Body
123 - Here
124
125 This is what borked because of new shiny, this is how migrate
126 EOF
127 )"
128
129 # Including scope for more precise changes
130 formatted-commit -t refactor -s "web/git-bug" -m "fancy shmancy" \
131 -b "Had to do a weird thing because..."
132
133
134 COMMANDS
135
136 help [command] Help about any command
137
138 FLAGS
139
140 -a --amend Amend the previous commit (optional)
141 -b --body Commit body (optional)
142 -B --breaking Mark as breaking change (optional)
143 -h --help Help for formatted-commit
144 -m --message Commit message (required)
145 -s --scope Commit scope (optional)
146 -T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
147 -t --type Commit type (required)
148 -v --version Version for formatted-commit
149```