1---
2name: formatting-commits
3description: Creates commits strictly following Conventional Commits format. ALWAYS read BEFORE committing changes, amending commits, or when the user mentions git commits, conventional commits, or commit messages.
4compatibility: Requires `git` and `git-format` CLI tools (invoked as `git formatted-commit`)
5license: AGPL-3.0-or-later
6metadata:
7 author: Amolith <amolith@secluded.site>
8---
9
10Create commits using `git formatted-commit`. For amends, choose the appropriate approach:
11
12- **Message stays accurate** → `git commit --amend --no-edit` (or `-a --amend --no-edit` to stage all)
13- **Message needs updating** → `git formatted-commit --amend` to reconstruct with new type/scope/body
14
15`git formatted-commit` has no sub-commands and the following options:
16
17<git_formatted-commit_flags>
18-t --type Commit type (required)
19-s --scope Commit scope (optional)
20-B --breaking Mark as breaking change (optional)
21-m --message Commit message (required)
22-b --body Commit body (optional)
23-T --trailer Trailer in 'Sentence-case-key: value' format (optional, repeatable)
24-a --add Stage all modified files before committing (optional)
25--amend Amend the previous commit (optional)
26-h --help
27</git_formatted-commit_flags>
28<git_formatted-commit_example>
29git formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -b "$(cat <<'EOF'
30Multi-line
31
32- Body
33- Here
34
35EOF
36)" -T "Fixes: https://todo.sr.ht/~user/tracker/#123"
37</git_formatted-commit_example>
38
39Most source code repositories require both an appropriate prefix _and_ scope. Necessity of scope increases with repository size; the smaller the repo, the less necessary the scope. Valid trailers for ticket tracking integration depend on the platform in use.
40
41- GitHub
42 - Closes:
43 - Fixes:
44 - Resolves:
45 - References:
46- SourceHut
47 - Closes:
48 - Fixes:
49 - Implements:
50 - References:
51
52Refer to [installing-git-format.md](references/installing-git-format.md) if it's unavailable.