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 requires conformance with the Conventional Commits specification
13through flags, made for LLMs and not really for humans (but I guess you can use
14this directly if you want). Humans would likely prefer, as the author does,
15[meteor](https://github.com/stefanlogue/meteor).
16
17## Installation
18
19As this is mostly meant for agentic coding tools, you'll need one. I like [Crush
20💘](https://github.com/charmbracelet/crush) (and maintain [a
21fork](https://git.secluded.site/crush)) or [OpenCode](https://opencode.ai/) as
22the best more-open options and [Amp](https://ampcode.com/) as the overall best
23option if you don't mind completely proprietary and paying for 100% of your API
24usage.
25
26You may install formatted-commits manually using the following command. You may
27also skip this and just add the prompt snippet; it tells the model about the
28command so it can try to run it on its own or ask you to run it.
29
30```bash
31go install git.secluded.site/formatted-commits@latest
32```
33
34Copy/paste this into wherever you tell your models how to write commits. For
35Crush, that might be `~/.config/crush/CRUSH.md` or `./CRUSH.md` in a repo. For
36[my Crush fork](https://git.secluded.site/crush) and Amp, that's
37`~/.config/AGENTS.md`. Look up where your tool checks for rules files and put
38this in a section like `## Creating git commits` or something.
39
40```markdown
41Create 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:
42<formatted-commit_flags>
43-b --body Commit body (optional)
44-B --breaking Mark as breaking change (optional)
45-h --help Help for formatted-commit
46-m --message Commit message (required)
47-s --scope Commit scope (optional)
48-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
49-t --type Commit type (required)
50-v --version Version for formatted-commit
51</formatted-commit_flags>
52<formatted-commit_example>
53formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -T "Crush <crush@charm.land>" -b "$(cat <<'EOF'
54Multi-line
55
56- Body
57- Here
58
59EOF
60)"
61</formatted-commit_example>
62```
63
64## Usage
65
66```text
67$ formatted-commit -h
68
69 formatted-commit helps you create well-formatted Git commits that follow
70 the Conventional Commits specification with proper subject length validation,
71 body wrapping, and trailer formatting.
72
73 USAGE
74
75
76 formatted-commit [--flags]
77
78
79 EXAMPLES
80
81
82 # With co-author
83 formatted-commit -t feat -m "do a thing" -T "Crush <crush@charm.land>"
84
85 # Breaking change with longer body
86 formatted-commit -t feat -m "do a thing that borks a thing" -B "$(cat <<'EOF'
87 Multi-line
88 - Body
89 - Here
90
91 This is what borked because of new shiny, this is how migrate
92 EOF
93 )"
94
95 # Including scope for more precise changes
96 formatted-commit -t refactor -s "web/git-bug" -m "fancy shmancy" \
97 -b "Had to do a weird thing because..."
98
99
100 COMMANDS
101
102 help [command] Help about any command
103
104 FLAGS
105
106 -b --body Commit body (optional)
107 -B --breaking Mark as breaking change (optional)
108 -h --help Help for formatted-commit
109 -m --message Commit message (required)
110 -s --scope Commit scope (optional)
111 -T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
112 -t --type Commit type (required)
113 -v --version Version for formatted-commit
114```