# Generate a commit message — commit

> commitbrief commit turns your staged diff into a commit message with --type formats and --generate alternatives, then runs git commit after you confirm.

CommitBrief docs · v1.x · Committing

Canonical URL: https://commitbrief.com/docs/1.x/commit

---

`commitbrief commit` generates a commit message from your **staged**
diff and, after you confirm, runs `git commit`. It is the only
CommitBrief command that writes to git — every review path is
read-only. It never auto-stages and never edits files: it commits
only what you already staged, and only on your confirmation (or
`--yes`).

Added in v1.5.0. See ADR-0019.

## Usage

```sh
commitbrief commit                          # suggest one message, confirm, commit
commitbrief commit -t conventional+body     # conventional subject + a generated body
commitbrief commit -g 4                      # pick from 4 alternatives
commitbrief commit --provider openai --model gpt-5.4-mini
commitbrief commit --yes                     # CI / non-interactive: commit the first suggestion
```

The scope is always the staged index, so the `--staged` / `--unstaged`
scope flags do not apply.

## What it does

1. Reads the staged diff (errors if nothing is staged).
2. Prints the detected staged files.
3. Runs the pre-send `.commitbrief/**` guard, the secret scan, and the
   cost preflight on the diff — exactly as a review does.
4. Asks the configured provider for the commit message(s) in a single call.
5. Shows the message (or an arrow-key selector for `--generate N`) and asks
   to confirm, pre-selected on **Yes**.
6. On Yes (or `--yes`), runs `git commit` and prints git's summary line.

The message is passed to git over stdin (`git commit -F -`), so multi-line
bodies commit verbatim. Commit hooks run normally (no `--no-verify`); a
failing `pre-commit` hook surfaces as an error.

## Flags

| Flag | Default | Effect |
|------|---------|--------|
| `-t, --type <format>` | `plain` (or `commit.type`) | Message format: `plain`, `conventional`, `conventional+body`, `gitmoji`, `subject+body`. |
| `-g, --generate <N>` | `1` (or `commit.generate`) | Produce N alternatives (1–10) and choose one in an arrow-key selector. A single provider call generates all N. |
| `--yes` | `false` | Commit the first suggestion with no prompt (non-interactive). Does **not** bypass the secret scan or cost preflight. |

Inherited globals that apply: `--provider` / `--model` / `--cli`,
`--no-cache`, `--allow-secrets`, `--no-cost-check`, `--verbose` /
`--quiet`, `--show-prompt`. Defaults resolve **flag > config >
built-in** — the `commit.type` and `commit.generate`
[config keys](/docs/1.x/configuration) set them when the flags are
omitted.

## Rejected flags

[Commit filters](/docs/1.x/review-scopes#commit-filters-v1150) —
`--author`, `--committer`, `--start-date`, `--end-date`, `--text` —
are rejected outright. `commit` describes the **staged index**, and
the index has no commits to select from.

## Message types

| `--type` | Output |
|----------|--------|
| `plain` (default) | A single short imperative subject line, no type prefix. |
| `conventional` | `type(scope): subject` ([Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)). Subject only. |
| `conventional+body` | Conventional subject plus a generated body. |
| `gitmoji` | An emoji matching the change, then a short subject. |
| `subject+body` | A subject line plus a generated body. |

Messages are always written in **English**, regardless of `--lang`
(which sets the AI output language for reviews and summaries).

## Non-interactive use

Committing needs a confirmation that can only be shown on a TTY. On a
non-TTY (piped or CI) **without** `--yes`, `commit` errors before
spending anything. Pass `--yes` to commit the first suggestion
unattended. Even with `--yes`, a detected secret (non-TTY) or an
over-threshold cost estimate still aborts — the
[pre-send guards](/docs/1.x/safety-and-cost) are not bypassed.

## How it relates to `--suggest-commit`

The `--suggest-commit` review flag is a read-only sibling: it prints one
Conventional Commit message **after a review** and never touches git.
`commit` is the standalone, write-capable command with format and
alternative-count options. Both are supported.

## See also

- [Safety, cost, and cache](/docs/1.x/safety-and-cost) — the pre-send guards `commit` shares with reviews.
- [Configuration](/docs/1.x/configuration) — the `commit.type` and `commit.generate` keys.
- [Providers](/docs/1.x/providers) — picking the backend with `--provider` / `--cli`.