1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# git-format
8
9[](https://goreportcard.com/report/git.secluded.site/git-format)
10[](https://api.reuse.software/info/git.secluded.site/git-format)
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`git-format` enforces all of this. Where possible, we "correct" the model's
28input. Where that's less possible, we error. For example, instead of requiring
29the model wrap body text at 72 columns, we let it write whatever body it wants
30and wrap it ourselves. We can't really fix the subject, so `git-format` emits an
31error when the subject is too long with clear indication of where the
3250-character cut-off is.
33
34## Installation
35
36You need _both_ the binary and [the skill].
37
38[the skill]: https://git.secluded.site/agent-skills#:~:text=formatting%2Dcommits%3A%20Creates%20commits%20strictly%20following%20Conventional%20Commits%20format%20via%20the%20formatted%2Dcommit%20CLI
39
40### The binary
41
42- Using [bin](https://github.com/marcosnils/bin) (highly recommended
43 because it's one tool to manage and update myriad CLI tools
44 distributed as statically-linked binaries, like _git-format_)
45 ```bash
46 bin install goinstall://git.secluded.site/git-format@latest
47 git-format install
48 ```
49- Using the [go toolchain](https://go.dev/dl) (upgrade with `git-format upgrade`)
50 ```bash
51 go install git.secluded.site/git-format@latest
52 git-format install
53 ```
54
55The `git-format install` command creates symlinks so you can invoke it as `git
56formatted-commit` and `git formatted-tag`.
57
58## Contributions
59
60Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
61new account to contribute, you don't need to fork this repo, you don't need to
62fiddle with `git send-email`, you don't need to faff with your email client to
63get `git request-pull` working...
64
65You just need:
66
67- Git
68- SSH
69- An SSH key
70
71```sh
72# Clone this repo, make your changes, and commit them
73# Create a new patch request with
74git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
75# After potential feedback, submit a revision to an existing patch request with
76git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
77# List patch requests
78ssh pr.pico.sh pr ls amolith/llm-projects
79```
80
81See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
82complete example workflow.
83
84[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
85[pr.pico.sh]: https://pr.pico.sh
86
87---
88
89Some other tools if this one interested you
90
91- [AgentSh](https://git.secluded.site/agentsh) - press `Ctrl+X` from any shell prompt to message your agent (Crush, Claude Code, etc.)
92- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix typos, translate, reformat)