Commands

The bc binary (alias better-commit) provides interactive commits and validation using your commit.config.ts.

Command overview

bc commit

Run the interactive commit flow. Prompts for type, scope, and subject based on config rules.

bc
bc commit

With aiSuggest configured, the CLI can propose a message from your staged diff before you confirm.

Staging behavior

If there are no staged files when running bc commit or bc retry, the CLI handles it adaptively:

• Clean repository: If there are no unstaged or staged changes, the CLI cancels early with No changes to commit.
• Small changes (≤ 10 files): Directly prompts you with an interactive multiselect menu where all unstaged files (including untracked files) are pre-selected. You can press Enter to stage all, or toggle selections to stage a subset.
• Large changes (> 10 files): Displays a menu first to choose between:
  1. Stage all files (X files)
  2. Select files interactively... (shows the multiselect menu)
  3. Cancel

Options

bc init

Create a starter commit.config.ts at the repository root.

bc init
bc init -q          # non-interactive
bc init -q -f       # overwrite existing config
bc init --hooks     # also install Husky prepare-commit-msg hook

Requires Husky for hooks: npm install -D husky && npx husky init

bc doctor

Verify your environment and configuration.

bc doctor

Checks Node version, config discovery, resolved plugins, and available AI providers.

bc check

Validate commit messages using the same rules as the interactive flow.

bc check                    # validate last commit
bc check --edit             # validate COMMIT_EDITMSG
bc check --from v1.0.0 --to HEAD   # validate commit range

Use only one mode: default (last commit), --edit, or --from/--to together.

Examples

Validate the message being composed (useful in a commit-msg hook):

bc check --edit

Validate all commits since a tag:

bc check --from v1.0.0 --to HEAD

Validate commits between two refs:

bc check --from abc1234 --to def5678

bc fix

Amend the last commit message interactively.

bc fix
bc fix --no-ai    # skip AI when suggesting a new message

bc retry

Retry the last interactive commit from cache when a previous attempt was interrupted.

bc retry

bc stack

List the local commits in the current branch stack starting from the detected base branch up to HEAD, showing their hashes, titles, and Change-Id footers.

bc stack
bc stack --base main

The CLI auto-detects the base branch by looking for the upstream tracking branch or common fallbacks (origin/main, origin/master, main, master).

bc amend

Amend a specific commit in the local stack using staged changes. It creates a fixup! commit and automatically runs a non-interactive Git autosquash rebase to merge the changes cleanly into the target commit while preserving its Change-Id footer.

bc amend 2
bc amend I8f9c0e2d
bc amend 323c58f

The <target> argument can be:

• A 1-based index from the bottom of the stack (e.g. 2 to amend the second commit).
• A Change-Id prefix or string (e.g. I8f9c0e2d).
• A commit SHA prefix (e.g. 323c58f).

If the rebase runs into merge conflicts, the CLI halts, explains the conflict, and leaves you in Git's normal rebase state where you can resolve files and run git rebase --continue.

Global options

See CI and hooks for pipeline and Git hook integration.