QuiCommit/docs/configuration-guide.en.md

# QuiCommit Configuration Guide

English | [简体中文](configuration-guide.md)

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` / `profile` subcommands
- **Environment variables and global options**
- **Common recipes** and **troubleshooting**

> For a feature overview, see [README.md](../README.md) (Chinese: [readme_zh.md](../readme_zh.md)).
> Definitions of configuration terms (Repo init, Config init, Initial branch, …) live in [CONTEXT.md](../CONTEXT.md).

---

## Table of Contents

1. [Quick Setup](#1-quick-setup)
2. [Config File Location and Precedence](#2-config-file-location-and-precedence)
3. [Detailed Settings by Category](#3-detailed-settings-by-category)
   - [3.1 Application Metadata (version / default_profile)](#31-application-metadata-version--default_profile)
   - [3.2 LLM and AI Generation ([llm])](#32-llm-and-ai-generation-llm)
   - [3.3 Git Identities (profiles.*)](#33-git-identities-profiles)
   - [3.4 Repository-to-Profile Mapping (repo_profiles)](#34-repository-to-profile-mapping-repo_profiles)
   - [3.5 Commit Settings ([commit])](#35-commit-settings-commit)
   - [3.6 Tag Settings ([tag])](#36-tag-settings-tag)
   - [3.7 Changelog Settings ([changelog])](#37-changelog-settings-changelog)
   - [3.8 Language Settings ([language])](#38-language-settings-language)
   - [3.9 Output Settings ([output])](#39-output-settings-output)
4. [Config Command Reference (quicommit config)](#4-config-command-reference-quicommit-config)
5. [Profile Command Reference (quicommit profile)](#5-profile-command-reference-quicommit-profile)
6. [Tokens and Credentials](#6-tokens-and-credentials)
7. [Environment Variables](#7-environment-variables)
8. [Global Options](#8-global-options)
9. [Full Configuration Example](#9-full-configuration-example)
10. [Common Recipes](#10-common-recipes)
11. [Troubleshooting](#11-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](../README.md#installation) |
| 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)

```bash
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:

```bash
quicommit init --yes
```

### Path B: Bootstrap a repo + configure the LLM manually

```bash
# 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

```bash
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):

1. The global CLI option `-c` / `--config <PATH>`
2. The environment variable `QUICOMMIT_CONFIG`
3. The platform default path above

```bash
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](https://github.com/0xPlaygrounds/rig): `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-models` prints a set of example model names for the current provider (for Ollama it tries to call the local `ollama list`).

#### The three API key storage modes

- `keyring` (default, recommended): stored in the system keyring; no plain text appears in `config.toml`. If the keyring is unavailable, `set-api-key` fails and suggests using an environment variable or `config`.
- `config`: written in plain text to `llm.api_key` in `config.toml`. Convenient but insecure; `set-api-key` prints a plain-text warning.
- `environment`: nothing is stored; you must set the environment variable yourself.

Setting and deleting:

```bash
# 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.

```toml
[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](../src/utils/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.

```bash
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 |

```bash
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) |

```bash
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.

```bash
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 ✓ / ✗ / ⚠ / → |

```bash
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 set` accepts only the keys above; anything else reports an "unknown config key" error.
> **The API key is not among them** — use `config set-api-key` / `config delete-api-key`.
> Boolean keys accept only the literals `true` / `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).

```bash
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:

```bash
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:

```bash
echo "protocol=https
host=github.com" | git credential reject
```

### Import, export, and backup

```bash
# 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 → (when `api_key_storage = "config"`) the config file.
> The provider-specific `QUICOMMIT_<PROVIDER>_API_KEY` is currently used only by `init`'s detection and the `config check-keyring` display; to have it feed generation, set `QUICOMMIT_API_KEY` instead.

---

## 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

```toml
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)

```bash
quicommit config set-llm ollama --base-url http://localhost:11434 --model llama2
quicommit config test-llm
```

### DeepSeek

```bash
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

```bash
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)

```bash
export QUICOMMIT_API_KEY=<KEY>        # the environment variable always wins
export QUICOMMIT_CONFIG=./ci-config.toml
quicommit commit --yes
```

### Enabling thinking mode

```bash
# 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)

```bash
# 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

```bash
quicommit config reset --force        # reset to defaults
quicommit init                        # reconfigure
```

### API key errors

```bash
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-key` did not take effect, or the environment variable is unset.
- A provider reports "not available": usually a `base_url` or credential problem. DeepSeek's default URL is `https://api.deepseek.com` (**without** `/v1`); if a legacy config explicitly wrote `/v1` and validation now fails, re-run `quicommit config set-llm deepseek`.

### Changes do not take effect

- Confirm you edited the effective config file: `quicommit config path` (remember `-c` / `QUICOMMIT_CONFIG` may 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

```bash
quicommit config edit                 # uses $EDITOR / $VISUAL
quicommit config show                 # read-only view
```