29 KiB
29 KiB
QuiCommit Configuration Guide
English | 简体中文
This guide is for readers who want a complete command of QuiCommit's configuration. It covers:
- Quick setup: get from "create a repo → configure an LLM → first commit" in three minutes
- Detailed settings by category: every field in the config file, its meaning, accepted values, and default
- Command reference: full tables for the
config/profilesubcommands - Environment variables and global options
- Common recipes and troubleshooting
For a feature overview, see README.md (Chinese: readme_zh.md). Definitions of configuration terms (Repo init, Config init, Initial branch, …) live in CONTEXT.md.
Table of Contents
- Quick Setup
- Config File Location and Precedence
- Detailed Settings by Category
- 3.1 Application Metadata (version / default_profile)
- 3.2 LLM and AI Generation ([llm])
- 3.3 Git Identities (profiles.*)
- 3.4 Repository-to-Profile Mapping (repo_profiles)
- 3.5 Commit Settings ([commit])
- 3.6 Tag Settings ([tag])
- 3.7 Changelog Settings ([changelog])
- 3.8 Language Settings ([language])
- 3.9 Output Settings ([output])
- Config Command Reference (quicommit config)
- Profile Command Reference (quicommit profile)
- Tokens and Credentials
- Environment Variables
- Global Options
- Full Configuration Example
- Common Recipes
- Troubleshooting
1. Quick Setup
Prerequisites
| Requirement | Notes |
|---|---|
| Git | Any version works (repo initialization uses libgit2, so it does not rely on git init -b) |
Rust / an installed quicommit |
See the README install section |
| System keyring (recommended) | Windows Credential Manager / macOS Keychain / Linux Secret Service. Used to store API keys and PATs securely. Check with quicommit config check-keyring |
Path A: Interactive wizard (recommended for first-time use)
quicommit init
The wizard asks, in order: output language → your first Git Profile (name / user name / email / description / work flag) → optional SSH → optional GPG → LLM provider → model → API key (hidden input, stored in the keyring). This is what CONTEXT.md calls Config init — it only creates QuiCommit's own config file and never touches a Git repository.
Skip every prompt and generate a minimal config from your local Git identity:
quicommit init --yes
Path B: Bootstrap a repo + configure the LLM manually
# 1. Turn the current directory into a Git repository
# (creates .git, writes README, generates .gitignore, sets the initial branch)
quicommit ginit
# 2. Choose an LLM provider (interactive when no provider is given)
quicommit config set-llm deepseek
# 3. Set the API key (omit the value for hidden input; a literal value leaks into shell history)
quicommit config set-api-key
# 4. Verify connectivity
quicommit config test-llm
# 5. First commit
quicommit commit
Verify the current configuration
quicommit config show # summarized view of all effective settings
quicommit config path # print the config file path
quicommit config get llm.provider
quicommit config check-keyring # check the keyring and related environment variables
2. Config File Location and Precedence
The configuration is a single TOML file whose default location is determined by the OS config directory:
| Platform | Default path |
|---|---|
| Linux | ~/.config/quicommit/config.toml |
| macOS | ~/Library/Application Support/quicommit/config.toml |
| Windows | %APPDATA%\quicommit\config.toml |
Specifying a custom path
Precedence (highest to lowest):
- The global CLI option
-c/--config <PATH> - The environment variable
QUICOMMIT_CONFIG - The platform default path above
quicommit -c ./my-config.toml config show
# or
QUICOMMIT_CONFIG=./my-config.toml quicommit config show
This path is shared by every subcommand (
commit,tag,changelog,profile,ginit, …). With a custom path, keyring entries are still keyed by provider / profile, independent of the config file path.
Where each value comes from
| Setting | Precedence (high → low) |
|---|---|
| Config file path | -c/--config > QUICOMMIT_CONFIG > platform default |
| API key | Environment variable (QUICOMMIT_API_KEY, always first within a process) > keyring (default storage) > llm.api_key in the config file (only when api_key_storage = "config") |
| Emoji decorations | --no-color (disables) > --no-emoji / --emoji > output.emoji config > on by default |
| Log level | RUST_LOG > number of -v flags |
Initial branch (ginit) |
-b/--branch > global init.defaultBranch > main |
3. Detailed Settings by Category
Each top-level table of the config file is documented field by field below. Every field lists key / type / default.
3.1 Application Metadata (version / default_profile)
| Key | Type | Default | Description |
|---|---|---|---|
version |
string | "1" |
Config schema version, used for future migrations; normally left alone |
default_profile |
string (optional) | none | Default Git identity. Used when profile apply is called without a name and by profile show without a name |
3.2 LLM and AI Generation ([llm])
QuiCommit talks to six providers through rig-core: ollama, openai, anthropic, kimi, deepseek, openrouter.
| Key | Type | Default | Description |
|---|---|---|---|
provider |
string | "ollama" |
Provider name, see the table below |
model |
string | "llama2" |
Model name. When switching providers, if the current model is empty or still llama2 it is replaced by that provider's default model |
base_url |
string (optional) | none (provider default) | Custom API base URL, for proxies, self-hosting, or regional endpoints |
max_tokens |
integer | 500 |
Maximum output tokens per generation |
temperature |
float | 0.6 |
Sampling temperature. Some providers override it (see "Temperature and thinking mode") |
timeout |
integer (seconds) | 30 |
HTTP request timeout |
api_key_storage |
string | "keyring" |
API key storage: keyring / config / environment |
api_key |
string (optional) | none | Only effective when api_key_storage = "config"; stored in plain text |
thinking_enabled |
bool | false |
Whether thinking/reasoning mode is on by default (--think on commit/tag/changelog overrides it per run) |
thinking_budget_tokens |
integer (optional) | none (treated as 1024 at runtime) |
Anthropic only: thinking budget in tokens |
Provider defaults at a glance
| provider | Default base_url |
Default model |
Needs an API key? |
|---|---|---|---|
ollama |
http://localhost:11434 |
llama2 |
No |
openai |
https://api.openai.com/v1 |
gpt-4 |
Yes |
anthropic |
https://api.anthropic.com/v1 |
claude-3-sonnet-20240229 |
Yes |
kimi |
https://api.moonshot.cn/v1 |
kimi-k2.6 |
Yes |
deepseek |
https://api.deepseek.com |
deepseek-v4-flash |
Yes |
openrouter |
https://openrouter.ai/api/v1 |
openai/gpt-3.5-turbo |
Yes |
quicommit config list-modelsprints a set of example model names for the current provider (for Ollama it tries to call the localollama list).
The three API key storage modes
keyring(default, recommended): stored in the system keyring; no plain text appears inconfig.toml. If the keyring is unavailable,set-api-keyfails and suggests using an environment variable orconfig.config: written in plain text tollm.api_keyinconfig.toml. Convenient but insecure;set-api-keyprints a plain-text warning.environment: nothing is stored; you must set the environment variable yourself.
Setting and deleting:
# Option 1: interactively choose provider / model / base_url / API key
quicommit config set-llm deepseek
# Option 2: non-interactive, pass values directly
# (--api-key lands in shell history; prefer it only for CI)
quicommit config set-llm openai --model gpt-4o --base-url https://api.openai.com/v1
# Set/delete the API key on its own (omit the value for hidden input)
quicommit config set-api-key
quicommit config delete-api-key
Temperature and thinking mode
--think (or thinking_enabled = true) takes effect only on deepseek, kimi, anthropic, and openai; other providers silently fall back to normal generation. Per-provider parameter handling:
| provider | Normal mode | Thinking mode |
|---|---|---|
ollama |
Uses temperature / max_tokens |
Not supported, falls back |
deepseek |
Uses temperature; sends thinking: disabled explicitly |
Omits temperature, streams |
kimi |
Forces temperature = 0.6 (ignores config) |
Forces temperature = 1.0, streams |
anthropic |
Uses temperature |
Omits temperature; raises max_tokens to at least thinking_budget_tokens + 100 (budget defaults to 1024); streams |
openai |
Uses temperature; o* models explicitly disable reasoning |
Omits temperature, streams |
openrouter |
Uses temperature / max_tokens |
Not supported, falls back |
CLI switches:
commit --think,tag --think,changelog --think.
3.3 Git Identities (profiles.*)
Each profile is a set of Git identity + authentication settings you can switch on independently. Create them with quicommit profile add (interactive) or by editing the config file directly.
Top-level fields:
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | none | Profile name; must match the TOML table name. Letters, digits, -, _ only, max 50 chars |
user_name |
string | none | Written to user.name |
user_email |
string | none | Written to user.email; must be a valid email address |
description |
string (optional) | none | Free-form note |
is_work |
bool | false |
Whether this is a work identity (a display/filter flag only) |
organization |
string (optional) | none | Organization name (meaningful when is_work = true) |
signing_key |
string (optional) | none | Explicit signing key; falls back to gpg.key_id when unset |
[profiles.<name>.settings] — behavioral preferences
| Key | Type | Default | Description |
|---|---|---|---|
auto_sign_commits |
bool | false |
When the profile is applied, write commit.gpgsign = true |
auto_sign_tags |
bool | false |
When the profile is applied, write tag.gpgsign = true |
default_commit_format |
string (optional) | none | Preferred commit format for this profile: conventional / commitlint |
repo_patterns |
array of strings | [] |
Path fragments used to match repositories to this profile |
llm_provider |
string (optional) | none | Preferred LLM provider for this profile (metadata, reserved) |
commit_template |
string (optional) | none | Custom commit message template |
[profiles.<name>.ssh] — SSH settings (optional)
| Key | Type | Default | Description |
|---|---|---|---|
private_key_path |
path (optional) | none | Path to the SSH private key (existence is validated) |
public_key_path |
path (optional) | none | Public key path; derived as <key>.pub from the private key when unset |
passphrase |
string (optional) | none | Key passphrase (stored encrypted) |
agent_forwarding |
bool | false |
Whether to add -A |
ssh_command |
string (optional) | none | Fully custom SSH command; overrides the other fields when set |
known_hosts_file |
path (optional) | none | Adds -o UserKnownHostsFile=<path> |
Applying writes core.sshCommand into the local Git config. Command assembly: ssh + (-A) + (-i <private key>) + (-o UserKnownHostsFile=<file>); if ssh_command is set, it is used as-is.
[profiles.<name>.gpg] — GPG settings (optional)
| Key | Type | Default | Description |
|---|---|---|---|
key_id |
string | none | GPG Key ID, 16–40 uppercase hex characters |
program |
string | Windows: gpg.exe; otherwise: gpg |
Written to gpg.program |
home_dir |
path (optional) | none | GPG home directory |
passphrase |
string (optional) | none | Passphrase (stored encrypted) |
use_agent |
bool | true |
Whether to use gpg-agent |
Applying writes gpg.program, user.signingkey, and — per settings.auto_sign_commits / settings.auto_sign_tags — commit.gpgsign / tag.gpgsign into the local Git config.
Applying (writing to Git) and display
profile apply / profile set-repo / profile switch write the profile into Git config:
- Repo-level:
user.name,user.email, plus the SSH / GPG keys noted above - Global (
profile apply --global): written into the global Git config
Applying a profile first clears "managed" keys that the new profile will not set (
core.sshCommand,user.signingkey,commit.gpgsign,tag.gpgsign,gpg.program) so stale identities do not linger.
3.4 Repository-to-Profile Mapping (repo_profiles)
Records "repository absolute path → profile name" so commands such as profile show can tell which identity a repository should use. It is written automatically by profile set-repo or ginit --profile; hand-editing is rarely needed.
[repo_profiles]
"/home/me/work/project" = "work"
"/home/me/personal/project" = "personal"
3.5 Commit Settings ([commit])
| Key | Type | Default | Description |
|---|---|---|---|
format |
string | "conventional" |
Commit format: conventional or commitlint |
auto_generate |
bool | true |
Whether to generate commit messages with AI by default (commit --manual turns it off per run) |
Format differences (see validators.rs):
conventional:<type>[scope][!]: <description>, where type is one of 11 (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert).commitlint: extends the conventional types (adds wip, init, update, remove, security) and additionally requires the subject not to start with an uppercase letter and not to end with a period.
quicommit config set commit.format conventional
quicommit config set-commit-format commitlint
quicommit config set commit.auto_generate false
3.6 Tag Settings ([tag])
| Key | Type | Default | Description |
|---|---|---|---|
version_prefix |
string | "v" |
Tag version prefix, e.g. v1.2.3 |
auto_generate |
bool | true |
Whether to generate tag messages with AI by default |
quicommit config set tag.version_prefix v
quicommit config set-version-prefix v
3.7 Changelog Settings ([changelog])
| Key | Type | Default | Description |
|---|---|---|---|
path |
string | "CHANGELOG.md" |
Changelog file path |
auto_generate |
bool | true |
Whether to generate changelogs with AI by default (--no-generate turns it off per run, using the template instead) |
quicommit config set changelog.path CHANGELOG.md
quicommit config set-changelog-path CHANGELOG.md
3.8 Language Settings ([language])
| Key | Type | Default | Description |
|---|---|---|---|
output_language |
string | "en" |
Language for UI and generated text |
keep_types_english |
bool | true |
Whether commit types (feat, fix, …) stay in English |
keep_changelog_types_english |
bool | true |
Whether changelog categories (Added, Fixed, …) stay in English |
Supported language codes: en, zh (including zh-cn / zh-tw), ja, ko, es, fr, de (full names such as english, chinese are also accepted). An invalid code silently falls back to English.
quicommit config set-language zh # omit the argument for an interactive picker
quicommit config set language.output_language zh
quicommit config set-keep-types-english true
quicommit config set-keep-changelog-types-english true
3.9 Output Settings ([output])
| Key | Type | Default | Description |
|---|---|---|---|
emoji |
bool | true |
Whether to show decorations such as ✓ / ✗ / ⚠ / → |
quicommit config set output.emoji false
CLI overrides: --no-color disables colors and decorations together; --emoji / --no-emoji control decorations alone.
4. Config Command Reference (quicommit config)
Alias: quicommit cfg. With no subcommand it behaves like config show.
| Subcommand | Description |
|---|---|
config show |
Summarized view of current settings (general / LLM / commit / tag / language / changelog / security) |
config path |
Print the config file path |
config edit |
Open the config file in $EDITOR (or $VISUAL) |
config get <key> |
Read a single setting |
config set <key> <value> |
Write a single setting (see the key table below) |
config set-llm [provider] |
Configure the LLM interactively; accepts --model / --base-url / --api-key |
config set-api-key [key] |
Set the current provider's API key (hidden input when omitted) |
config delete-api-key |
Delete the API key from the current storage backend |
config set-commit-format <fmt> |
Set conventional / commitlint |
config set-version-prefix <prefix> |
Set the tag version prefix |
config set-changelog-path <path> |
Set the changelog path |
config set-language [code] |
Set the output language (interactive when omitted) |
config set-keep-types-english <bool> |
Keep commit types in English |
config set-keep-changelog-types-english <bool> |
Keep changelog categories in English |
config list-models |
List example/installed models for the current provider |
config test-llm |
Send a test request to verify provider connectivity |
config check-keyring |
Check keyring availability and related environment variables |
config export -o <file> [--password] |
Export the config (optionally encrypted) |
config import -i <file> [--password] |
Import a config |
config reset [--force] |
Reset to defaults |
Keys accepted by config set / config get
| Key | Values |
|---|---|
llm.provider |
ollama / openai / anthropic / kimi / deepseek / openrouter |
llm.model |
any model name |
llm.base_url |
a URL |
llm.max_tokens |
integer |
llm.temperature |
float |
llm.timeout |
integer (seconds) |
llm.thinking_enabled |
true / false |
llm.thinking_budget_tokens |
integer |
llm.api_key_storage |
keyring / config / environment |
commit.format |
conventional / commitlint |
commit.auto_generate |
true / false |
tag.version_prefix |
string |
tag.auto_generate |
true / false |
changelog.path |
path string |
changelog.auto_generate |
true / false |
language.output_language |
language code |
language.keep_types_english |
true / false |
language.keep_changelog_types_english |
true / false |
output.emoji |
true / false |
config setaccepts only the keys above; anything else reports an "unknown config key" error. The API key is not among them — useconfig set-api-key/config delete-api-key. Boolean keys accept only the literalstrue/false.
5. Profile Command Reference (quicommit profile)
Alias: quicommit p. With no subcommand it behaves like profile list.
| Subcommand | Description |
|---|---|
profile add |
Create a profile interactively (name / user name / email / description / work flag / SSH / GPG / tokens) |
profile list |
List all profiles (the default is marked ●) |
profile show [name] |
Show the current repo's Git config, the matched profile, and details |
profile edit <name> |
Edit interactively, with SSH / GPG / signing / tokens submenus |
profile copy <from> <to> |
Duplicate a profile (usage stats are not copied) |
profile remove <name> |
Delete a profile (also clears its keyring PATs) |
profile set-default <name> |
Set the default profile |
profile set-repo <name> |
Record the mapping for the current repo and apply it immediately |
profile switch |
Switch the default profile interactively, optionally applying it to the current repo |
profile apply [name] [--global] |
Apply a profile (defaults to default) to the current repo or the global Git config |
profile check [name] |
Compare a profile against the current repo's Git config |
profile stats [name] |
Show usage statistics |
profile token add <profile> <service> |
Add a service token (stored in the keyring) |
profile token remove <profile> <service> |
Remove a service token |
profile token list <profile> |
List tokens and their storage status |
6. Tokens and Credentials
PAT (Personal Access Token)
PATs are used to push to private repositories on GitHub / GitLab and similar platforms. They are stored in the system keyring keyed by profile + service name (config.toml only records metadata such as type, description, and whether it is stored).
quicommit profile token add personal github
quicommit profile token list personal
quicommit profile token remove personal github
The service name is free-form (github, gitlab, bitbucket, …).
Git Credential Helper
QuiCommit can act as a Git credential helper; once registered, Git asks it for the PAT during a push:
git config --global credential.helper quicommit
# or limit it to one host
git config --global credential.https://github.com.helper quicommit
credential get|store|erase is invoked automatically by Git and hidden from --help. To delete a stored credential:
echo "protocol=https
host=github.com" | git credential reject
Import, export, and backup
# Plain-text export (PATs in the keyring are not included)
quicommit config export -o config-backup.toml
# Encrypted export (profile PATs are encrypted and bundled too)
quicommit config export -o config-backup.enc --password
# Import
quicommit config import -i config-backup.toml
quicommit config import -i config-backup.enc --password
The encrypted export uses AES-GCM + Argon2; the file is prefixed with
ENCRYPTED:. If a target config holds PATs but encryption is not enabled, import/export prints a plain-text warning.
7. Environment Variables
| Variable | Description |
|---|---|
QUICOMMIT_CONFIG |
Config file path (equivalent to -c/--config) |
QUICOMMIT_API_KEY |
API key for any provider; always first within the process, ahead of the keyring and the config file |
QUICOMMIT_<PROVIDER>_API_KEY |
Provider-specific API key (e.g. QUICOMMIT_OPENAI_API_KEY). Detected by the interactive init and shown by config check-keyring |
EDITOR / VISUAL |
Editor used by config edit (EDITOR wins) |
NO_COLOR |
Setting any value disables colors and emoji decorations |
RUST_LOG |
Overrides -v log filtering, e.g. RUST_LOG=debug |
Note: the key resolution path used for real generation requests is
QUICOMMIT_API_KEY→ keyring → (whenapi_key_storage = "config") the config file. The provider-specificQUICOMMIT_<PROVIDER>_API_KEYis currently used only byinit's detection and theconfig check-keyringdisplay; to have it feed generation, setQUICOMMIT_API_KEYinstead.
8. Global Options
All subcommands share these global options:
| Option | Description |
|---|---|
-v, --verbose (repeatable) |
-v info, -vv debug, -vvv trace |
-c, --config <PATH> |
Config file path |
--no-color |
Disable colors and emoji decorations (highest priority) |
--emoji / --no-emoji |
Force emoji decorations on/off, overriding output.emoji |
9. Full Configuration Example
version = "1"
default_profile = "personal"
# -- LLM ------------------------------------------------------------
[llm]
provider = "deepseek"
model = "deepseek-v4-flash"
# base_url = "https://api.deepseek.com" # omit to use the provider default
max_tokens = 500
temperature = 0.6
timeout = 30
api_key_storage = "keyring"
thinking_enabled = false
# thinking_budget_tokens = 1024 # Anthropic only
# -- Commit / tag / changelog --------------------------------------
[commit]
format = "conventional"
auto_generate = true
[tag]
version_prefix = "v"
auto_generate = true
[changelog]
path = "CHANGELOG.md"
auto_generate = true
# -- Language and output -------------------------------------------
[language]
output_language = "en"
keep_types_english = true
keep_changelog_types_english = true
[output]
emoji = true
# -- Personal identity ---------------------------------------------
[profiles.personal]
name = "personal"
user_name = "Your Name"
user_email = "you@example.com"
description = "Personal projects"
is_work = false
[profiles.personal.settings]
auto_sign_commits = false
auto_sign_tags = false
repo_patterns = []
# -- Work identity (with SSH + GPG) --------------------------------
[profiles.work]
name = "work"
user_name = "Your Name"
user_email = "you@company.com"
description = "Work projects"
is_work = true
organization = "Your Company"
[profiles.work.settings]
auto_sign_commits = true
auto_sign_tags = true
default_commit_format = "conventional"
repo_patterns = ["/work/"]
[profiles.work.ssh]
private_key_path = "/home/user/.ssh/id_ed25519_work"
agent_forwarding = true
[profiles.work.gpg]
key_id = "0123456789ABCDEF"
program = "gpg"
use_agent = true
# -- Repo -> identity mapping --------------------------------------
[repo_profiles]
"/home/user/work/project" = "work"
"/home/user/personal/project" = "personal"
10. Common Recipes
Local Ollama (no API key)
quicommit config set-llm ollama --base-url http://localhost:11434 --model llama2
quicommit config test-llm
DeepSeek
quicommit config set-llm deepseek --model deepseek-v4-flash
quicommit config set-api-key # hidden input
# or in one shot: quicommit config set-llm deepseek --api-key <KEY>
Dual work / personal identities
quicommit profile add # create "personal"
quicommit profile add # create "work" (optionally with SSH/GPG)
quicommit profile set-default personal
cd ~/work/project
quicommit profile set-repo work # record the mapping and apply it immediately
quicommit profile check work # verify it matches the repo's Git config
In CI (no keyring)
export QUICOMMIT_API_KEY=<KEY> # the environment variable always wins
export QUICOMMIT_CONFIG=./ci-config.toml
quicommit commit --yes
Enabling thinking mode
# Just this commit
quicommit commit --think
# On by default (takes effect for deepseek/kimi/anthropic/openai)
quicommit config set llm.thinking_enabled true
Headless Linux (no Secret Service)
# Option 1: use an environment variable
export QUICOMMIT_API_KEY=<KEY>
# Option 2: store it in the config file (plain text; mind the file permissions)
quicommit config set llm.api_key_storage config
quicommit config set-api-key
11. Troubleshooting
Corrupted config or an incompatible upgrade
quicommit config reset --force # reset to defaults
quicommit init # reconfigure
API key errors
quicommit config check-keyring # is the keyring available, are env vars picked up?
quicommit config show # confirm provider and key mask status
quicommit config test-llm # end-to-end connectivity
- "keyring is not available": the system has no Secret Service (common on headless Linux). Use an environment variable or
api_key_storage = config. - "API key not configured":
set-api-keydid not take effect, or the environment variable is unset. - A provider reports "not available": usually a
base_urlor credential problem. DeepSeek's default URL ishttps://api.deepseek.com(without/v1); if a legacy config explicitly wrote/v1and validation now fails, re-runquicommit config set-llm deepseek.
Changes do not take effect
- Confirm you edited the effective config file:
quicommit config path(remember-c/QUICOMMIT_CONFIGmay change the path). - Check whether a global option overrides the config:
--emoji,--no-emoji,--think. - Check environment-variable precedence:
QUICOMMIT_API_KEY,RUST_LOG.
Opening the config file
quicommit config edit # uses $EDITOR / $VISUAL
quicommit config show # read-only view