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