1# Conventional Commits
 2
 3Create commits using `git formatted-commit`. For amends, choose the appropriate
 4approach:
 5
 6- **Message stays accurate** → `git commit --amend --no-edit` (or `-a --amend --no-edit` to stage all)
 7- **Message needs updating** → `git formatted-commit --amend` to reconstruct with new type/scope/body
 8
 9`git formatted-commit` has no sub-commands and the following options:
10
11```
12-t --type      Commit type (required)
13-s --scope     Commit scope (optional)
14-B --breaking  Mark as breaking change (optional)
15-m --message   Commit message (required)
16-b --body      Commit body (optional)
17-T --trailer   Trailer in 'Sentence-case-key: value' format (optional, repeatable)
18-a --add       Stage all modified files before committing (optional)
19--amend        Amend the previous commit (optional)
20-h --help
21```
22
23Example:
24
25```bash
26git formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -b "$(cat <<'EOF'
27Multi-line
28
29- Body
30- Here
31
32EOF
33)" -T "Fixes: https://todo.sr.ht/~user/tracker/#123"
34```
35
36Most source code repositories require both an appropriate prefix _and_ scope.
37Necessity of scope increases with repository size; the smaller the repo, the
38less necessary the scope.
39
40Refer to [installing-git-format.md](installing-git-format.md) for setup. If
41`git formatted-commit` is unavailable and cannot be installed, fall back to the
42format script: assemble the subject as `type(scope): message` (or
43`type(scope)!: message` for breaking changes), write the full message with body
44and trailers, and pipe through `scripts/format message`.