Configuration
Share settings with your team, and every option explained.
Settings that should be shared by everyone on a project go in a config file committed to the repository. Create one with:
gitmit init
Config files
gitmit uses the first of these it finds in the repository root:
gitmit.config.ts(also.mts,.cts,.js,.mjs,.cjs).gitmitrc.json.gitmitrc(JSON)- A
"gitmit"key inpackage.json
A TypeScript config gets full autocomplete:
// gitmit.config.ts
import { defineConfig } from "@gitmit/cli";
export default defineConfig({
types: ["feat", "fix", "docs", "refactor", "test", "chore"],
scopeFromPaths: {
"apps/web/**": "web",
"apps/api/**": "api",
"packages/ui/**": "ui",
},
ticket: { position: "suffix" },
subjectMaxLength: 72,
bodyStyle: "bullets",
});
This works even when gitmit is installed globally and the repository doesn't list @gitmit/cli as a dependency.
JSON configs get autocomplete through the published schema:
{
"$schema": "https://unpkg.com/@gitmit/cli/schema.json",
"types": ["feat", "fix", "docs", "chore"],
"bodyStyle": "none"
}
Personal defaults
Your own preferences for every repository go in ~/.config/gitmit/config.json (%APPDATA%\gitmit\config.json on Windows), in the same format. Project settings override them.
Order of priority, highest first:
- Command-line flags
- The project config
- Your personal config
- Built-in defaults
Run gitmit config to see the result and which file each setting came from. API keys never go in config files; they belong in your environment or your personal .env.
All settings
| Setting | Type | Default | What it does |
|---|---|---|---|
provider | "openai" | "anthropic" | "ollama" | "rules" | first provider with a key, else rules | Where suggestions come from. |
model | string | per provider | Model name for the provider. |
types | string[] | the 11 Conventional Commits types | Allowed commit types. Custom ones like "wip" are fine. |
scopes | string[] | any | Allowed scopes. |
scopeFromPaths | { glob: scope } | built-in rules | Map paths to scopes. The first matching glob wins. |
ticket | object | off | Add a ticket ID from the branch name. See below. |
subjectMaxLength | number (20 to 200) | 72 | Maximum header length, including any ticket. |
bodyStyle | "none" | "prose" | "bullets" | "bullets" | Format of the message body. |
bodyLineLength | number (40 to 200) | 72 | Wrap body lines at this width. |
language | string | "en" | Language of the description and body, e.g. "fr". |
ignore | string[] | none | Extra globs to treat as noise (listed, never sent to a model). |
secrets.onDetect | "abort" | "redact" | "abort" | What happens when a secret is found before a remote call. |
variants | number (1 to 5) | 3 | How many suggestions to show. |
commitlint | boolean | true | Follow the repository's commitlint config when there is one. |
push | boolean | false | Push after every successful commit or split. |
The 11 default types are feat, fix, docs, style, refactor, perf, test, build, ci, chore and revert.
How scopes are chosen
Without scopeFromPaths, gitmit infers a scope from where the changed files live:
| Path | Scope |
|---|---|
apps/web/src/App.tsx | web (also packages/, services/, libs/, modules/, crates/, plugins/, extensions/) |
src/auth/login.ts | auth (also under lib/, app/, pkg/, internal/, cmd/) |
api/handlers/users.go | api (a top-level folder, unless it's generic like docs or scripts) |
README.md, src/index.ts | no scope |
If the changes span several scopes, gitmit leaves the scope out rather than guess. Consider gitmit split in that case.