Usage

Every run follows the same path. Stage changes, run gitcomm, choose a message, and decide whether to push.

Basic workflow

gitcomm only looks at staged changes by default, so decide what belongs in this commit before you run it:

git status
git add src/auth/login.ts
git add -p src/routes/web.ts
npx gitcomm

When the commit lands, review the result as usual:

git show --stat

Choosing what to stage

Two flags change what goes into the diff gitcomm reads.

# Stage every tracked change first (git add -u)
npx gitcomm --all

# Never auto-stage; use only what is already staged
npx gitcomm --stageddonly

--all uses git add -u, which stages modifications and deletions to files Git already tracks. It does not add untracked files. Use --stageddonly in scripts and hooks where an unexpected git add would be a surprise.

Reviewing suggestions

gitcomm asks for three candidates by default and lists them in the order it ranks them. The first is the one it would pick. Request more with --count:

npx gitcomm --count 5
npx gitcomm --count 1

The accepted range is 1 to 5. Outside that, gitcomm falls back to the default of three.

Two options in the list are always there: Write my own message, which opens your editor with the selected subject pre-filled, and Cancel, which exits without committing.

Commit and push in one go

--push runs git push after a commit succeeds:

npx gitcomm --push

For a branch you are done with, --commit skips the final confirmation and --yes skips the prompt entirely, taking the top suggestion:

npx gitcomm -a -y -c --push

That one line stages tracked changes, takes the first suggestion, commits, and pushes. It is the shortest path from a dirty working tree to a pushed branch.

Dry runs and scripts

To see the message without writing a commit:

npx gitcomm --dry-run

To pipe subjects somewhere without any prompts at all:

npx gitcomm --print

--print writes candidate subjects to stdout and exits, which makes it easy to feed a changelog generator or a ticket template.

Forcing a type and scope

Detected hints are a starting point. Override them when you already know what the commit is:

npx gitcomm -t fix
npx gitcomm -t feat -s auth

If your repository does not use Conventional Commits and you want messages in that format anyway, add --force-conventional:

npx gitcomm --force-conventional

Choosing a language

gitcomm follows the language your history is written in. Force it when detection guesses wrong:

npx gitcomm --language en
npx gitcomm --language id
npx gitcomm --language auto

auto is the default and reads the language from your commit subjects.

Working offline

Rule-based suggestions need no network and no API key:

npx gitcomm --offline

The same engine runs on its own if the service is unreachable or rate limited, so you always get something to pick from. Offline suggestions still follow your repository's style and name the affected unit, but they cannot read file contents, so they read as more generic than the ones the service returns.

Git hooks

To skip pre-commit and commit-msg hooks for one commit:

npx gitcomm --no-verify