# Conventional Commits

Create commits using `git formatted-commit`. For amends, choose the appropriate
approach:

- **Message stays accurate** → `git commit --amend --no-edit` (or `-a --amend --no-edit` to stage all)
- **Message needs updating** → `git formatted-commit --amend` to reconstruct with new type/scope/body

`git formatted-commit` has no sub-commands and the following options:

```
-t --type      Commit type (required)
-s --scope     Commit scope (optional)
-B --breaking  Mark as breaking change (optional)
-m --message   Commit message (required)
-b --body      Commit body (optional)
-T --trailer   Trailer in 'Sentence-case-key: value' format (optional, repeatable)
-a --add       Stage all modified files before committing (optional)
--amend        Amend the previous commit (optional)
-h --help
```

Example:

```bash
git formatted-commit -t feat -s "web/git-bug" -m "do a fancy new thing" -b "$(cat <<'EOF'
Multi-line

- Body
- Here

EOF
)" -T "Fixes: https://todo.sr.ht/~user/tracker/#123"
```

Most 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.

Refer to [installing-git-format.md](installing-git-format.md) for setup. If
`git formatted-commit` is unavailable and cannot be installed, fall back to the
format script: assemble the subject as `type(scope): message` (or
`type(scope)!: message` for breaking changes), write the full message with body
and trailers, and pipe through `scripts/format message`.