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
42Pre-built binaries are available at
43[releases.secluded.site/git-format/latest](https://releases.secluded.site/git-format/latest).
44
45- Using [mise](https://mise.jdx.dev/) (recommended), copy the snippet from the
46 releases page into your `mise.toml` or global `~/.config/mise/config.toml` to
47 automate updates.
48- Without mise, or a similar tool, download the binary for your platform from
49 the releases page and place it somewhere in your `$PATH`.
50
51Then run `git-format install` tr create symlinks so you can invoke it as `git
52formatted-commit` and `git formatted-tag`.
53
54## Contributions
55
56Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't need a
57new account to contribute, you don't need to fork this repo, you don't need to
58fiddle with `git send-email`, you don't need to faff with your email client to
59get `git request-pull` working...
60
61You just need:
62
63- Git
64- SSH
65- An SSH key
66
67```sh
68# Clone this repo, make your changes, and commit them
69# Create a new patch request with
70git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
71# After potential feedback, submit a revision to an existing patch request with
72git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
73# List patch requests
74ssh pr.pico.sh pr ls amolith/llm-projects
75```
76
77See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
78complete example workflow.
79
80[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
81[pr.pico.sh]: https://pr.pico.sh
82
83---
84
85Some other tools if this one interested you
86
87- [AgentSh](https://git.secluded.site/agentsh) - press `Ctrl+X` from any shell prompt to message your agent (Crush, Claude Code, etc.)
88- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix typos, translate, reformat)