Files
QuiCommit/docs/configuration-guide.md

29 KiB
Raw Permalink Blame History

QuiCommit 配置指南

English | 简体中文

本指南面向希望完整掌握 QuiCommit 配置的读者,覆盖:

  • 快速设置:三分钟跑通「建仓库 → 配 LLM → 第一次提交」
  • 分类详细设置:逐项说明配置文件里每个字段的含义、取值与默认值
  • 命令参考:config / profile 子命令全表
  • 环境变量与全局选项
  • 常见场景配方与故障排除

想先看功能全貌,请阅读 README(中文版 readme_zh.md)。 配置术语(Repo init、Config init、Initial branch 等)的定义见 CONTEXT.md。


目录

  1. 快速设置
  2. 配置文件位置与优先级
  3. 分类详细设置
  4. 配置命令参考(quicommit config)
  5. 身份配置命令参考(quicommit profile)
  6. 令牌与凭据
  7. 环境变量
  8. 全局选项
  9. 完整配置示例
  10. 常见场景配方
  11. 故障排除

1. 快速设置

前置条件

依赖 说明
Git 任意版本均可(仓库初始化走 libgit2,不依赖 git init -b)
Rust / 已安装的 quicommit 见 README 安装章节
系统密钥环(推荐) Windows 凭据管理器 / macOS Keychain / Linux Secret Service。用于安全存放 API Key 与 PAT。用 quicommit config check-keyring 检查

路线 A:交互式向导(推荐首次使用)

quicommit init

向导依次询问:输出语言 → 第一个 Git Profile(名称 / 用户名 / 邮箱 / 描述 / 是否工作身份)→ 可选 SSH → 可选 GPG → LLM provider → 模型 → API Key(隐藏输入,存入密钥环)。这与 CONTEXT.md 所说的 Config init 对应——只创建 QuiCommit 自己的配置文件,不碰 Git 仓库。

跳过所有提问、使用本机 Git 身份生成一份最小配置:

quicommit init --yes

路线 B:仓库起步 + 手动配 LLM

# ① 把当前目录变成 Git 仓库(建库、写 README、生成 .gitignore、定初始分支)
quicommit ginit

# ② 选择 LLM provider(无参数时进入交互选择)
quicommit config set-llm deepseek

# ③ 设置 API Key(省略值可隐藏输入;已带值时注意 shell 历史泄露)
quicommit config set-api-key

# ④ 验证连通性
quicommit config test-llm

# ⑤ 第一次提交
quicommit commit

验证当前配置

quicommit config show          # 汇总展示所有生效配置
quicommit config path          # 打印配置文件路径
quicommit config get llm.provider
quicommit config check-keyring # 检查密钥环与相关环境变量

2. 配置文件位置与优先级

配置文件是单个 TOML 文件,默认位置由操作系统的配置目录决定:

平台 默认路径
Linux ~/.config/quicommit/config.toml
macOS ~/Library/Application Support/quicommit/config.toml
Windows %APPDATA%\quicommit\config.toml

指定自定义路径

优先级(从高到低):

  1. 命令行全局选项 -c / --config <PATH>
  2. 环境变量 QUICOMMIT_CONFIG
  3. 上述平台默认路径
quicommit -c ./my-config.toml config show
# 或
QUICOMMIT_CONFIG=./my-config.toml quicommit config show

该路径会被所有子命令共享(commit、tag、changelog、profile、ginit 等)。 用自定义路径时,密钥环条目仍按 provider / profile 维度存取,与配置文件路径无关。

配置来源优先级汇总

配置项 优先级(高 → 低)
配置文件路径 -c/--config > QUICOMMIT_CONFIG > 平台默认
API Key 环境变量(QUICOMMIT_API_KEY,进程内始终优先) > 密钥环(默认存储方式) > 配置文件内 llm.api_key(仅当 api_key_storage = "config")
Emoji 装饰 --no-color(关闭) > --no-emoji / --emoji > 配置 output.emoji > 默认开启
日志级别 RUST_LOG > -v 次数
Initial branch(ginit) -b/--branch > 全局 init.defaultBranch > main

3. 分类详细设置

下面按配置文件的顶层表(table)逐项说明。每个字段都给出 键名 / 类型 / 默认值。

3.1 应用元信息(version / default_profile)

键 类型 默认值 说明
version string "1" 配置结构版本,用于未来迁移,一般不手动改动
default_profile string(可省略) 无 默认 Git 身份名。profile apply 不带参数、profile show 不带参数时使用它

3.2 LLM 与 AI 生成([llm])

QuiCommit 通过 rig-core 统一对接六家 provider:ollama、openai、anthropic、kimi、deepseek、openrouter。

键 类型 默认值 说明
provider string "ollama" provider 名称,见下表
model string "llama2" 模型名。切换 provider 时若当前模型为空或仍是 llama2,会自动替换为该 provider 的默认模型
base_url string(可省略) 无(用 provider 默认) 自定义 API 地址,用于代理、私有部署或国内镜像
max_tokens 整数 500 单次生成的最大输出 token 数
temperature 浮点 0.6 采样温度。部分 provider 会覆盖它(见「温度与思考模式」)
timeout 整数(秒) 30 HTTP 请求超时
api_key_storage string "keyring" API Key 存储方式:keyring / config / environment
api_key string(可省略) 无 仅当 api_key_storage = "config" 时生效,明文存于配置文件
thinking_enabled 布尔 false 默认是否启用思考/推理模式(commit/tag/changelog 的 --think 可临时覆盖)
thinking_budget_tokens 整数(可省略) 无(运行期按 1024 处理) 仅 Anthropic 使用:思考预算 token

Provider 默认值速查

provider 默认 base_url 默认 model 是否需要 API Key
ollama http://localhost:11434 llama2 否
openai https://api.openai.com/v1 gpt-4 是
anthropic https://api.anthropic.com/v1 claude-3-sonnet-20240229 是
kimi https://api.moonshot.cn/v1 kimi-k2.6 是
deepseek https://api.deepseek.com deepseek-v4-flash 是
openrouter https://openrouter.ai/api/v1 openai/gpt-3.5-turbo 是

quicommit config list-models 会按当前 provider 打印一批示例模型名(Ollama 会尝试直接调用本机 ollama list)。

API Key 的三种存储方式

  • keyring(默认,推荐):存入系统密钥环,config.toml 中不出现明文。密钥环不可用时 set-api-key 会报错并提示改用环境变量或 config。
  • config:明文写入 config.toml 的 llm.api_key。方便但不安全,set-api-key 会给出明文告警。
  • environment:不存储,要求你自行设置环境变量。

设置与删除:

# 方式一:交互式选择 provider / 模型 / base_url / API Key
quicommit config set-llm deepseek

# 方式二:非交互,直接给出参数(--api-key 会进入 shell 历史,建议仅用于 CI)
quicommit config set-llm openai --model gpt-4o --base-url https://api.openai.com/v1

# 单独设置/删除 API Key(省略值则隐藏输入)
quicommit config set-api-key
quicommit config delete-api-key

温度与思考模式

--think(或配置 thinking_enabled = true)只在 deepseek、kimi、anthropic、openai 上生效;其余 provider 会自动降级为普通生成。各 provider 的参数处理如下:

provider 普通模式 思考模式
ollama 使用 temperature / max_tokens 不支持,降级
deepseek 使用 temperature;显式传 thinking: disabled 省略 temperature,走流式
kimi 强制 temperature = 0.6(忽略配置) 强制 temperature = 1.0,走流式
anthropic 使用 temperature 省略 temperature;max_tokens 提升到至少 thinking_budget_tokens + 100,预算缺省 1024;走流式
openai 使用 temperature;o* 系列模型显式关闭推理 省略 temperature,走流式
openrouter 使用 temperature / max_tokens 不支持,降级

命令层开关:commit --think、tag --think、changelog --think。

3.3 Git 身份配置([profiles.*])

每个 profile 是一组可独立启用的 Git 身份 + 认证设置。用 quicommit profile add(交互式)创建,或直接编辑配置文件。

顶层字段:

键 类型 默认值 说明
name string 无 profile 名,须与 TOML 表名一致。只允许字母、数字、-、_,最长 50 字符
user_name string 无 写入 user.name
user_email string 无 写入 user.email,须符合邮箱格式
description string(可省略) 无 备注
is_work 布尔 false 是否工作身份(仅作展示/筛选标记)
organization string(可省略) 无 组织名(is_work = true 时有意义)
signing_key string(可省略) 无 直接指定签名 key;未设置时回退到 gpg.key_id

[profiles.<name>.settings] — 行为偏好

键 类型 默认值 说明
auto_sign_commits 布尔 false 应用该 profile 时是否写入 commit.gpgsign = true
auto_sign_tags 布尔 false 应用该 profile 时是否写入 tag.gpgsign = true
default_commit_format string(可省略) 无 该 profile 偏好的提交格式:conventional / commitlint
repo_patterns 字符串数组 [] 用于把仓库路径匹配到该 profile 的路径片段
llm_provider string(可省略) 无 该 profile 偏好的 LLM provider(元数据,供未来使用)
commit_template string(可省略) 无 自定义提交信息模板

[profiles.<name>.ssh] — SSH 配置(可选)

键 类型 默认值 说明
private_key_path 路径(可省略) 无 SSH 私钥路径(校验存在性)
public_key_path 路径(可省略) 无 公钥路径;未设置时按私钥推导 <key>.pub
passphrase string(可省略) 无 私钥口令(加密存储)
agent_forwarding 布尔 false 是否加 -A
ssh_command string(可省略) 无 完全自定义的 SSH 命令;设置后覆盖其他字段
known_hosts_file 路径(可省略) 无 追加 -o UserKnownHostsFile=<path>

应用时写入 Git 本地配置 core.sshCommand。命令拼接规则:ssh +(-A)+(-i <私钥>)+(-o UserKnownHostsFile=<文件>);若 ssh_command 有值则直接使用它。

[profiles.<name>.gpg] — GPG 配置(可选)

键 类型 默认值 说明
key_id string 无 GPG Key ID,须为 16–40 位十六进制大写字符
program string Windows:gpg.exe;其他:gpg 写入 gpg.program
home_dir 路径(可省略) 无 GPG home 目录
passphrase string(可省略) 无 口令(加密存储)
use_agent 布尔 true 是否使用 gpg-agent

应用时写入 Git 本地配置 gpg.program、user.signingkey,并按 settings.auto_sign_commits / auto_sign_tags 写入 commit.gpgsign / tag.gpgsign。

应用(写出到 Git)与展示

profile apply / profile set-repo / profile switch 会把 profile 写入 Git 配置:

  • 仓库级:user.name、user.email,以及上面提到的 SSH / GPG 相关键
  • 全局(profile apply --global):写入全局 Git 配置

应用 profile 时会先清理「新 profile 不再设置」的受管键(core.sshCommand、user.signingkey、commit.gpgsign、tag.gpgsign、gpg.program),避免残留旧身份。

3.4 仓库到身份映射([repo_profiles])

把「仓库绝对路径 → profile 名」记录下来,供 profile show 等命令识别当前仓库应使用哪个身份。由 profile set-repo 或 ginit --profile 自动写入,一般无需手改。

[repo_profiles]
"/home/me/work/project" = "work"
"/home/me/personal/project" = "personal"

3.5 提交配置([commit])

键 类型 默认值 说明
format string "conventional" 提交格式:conventional 或 commitlint
auto_generate 布尔 true 是否默认用 AI 生成提交信息(commit --manual 可临时关闭)

格式差异(见 validators.rs):

  • conventional:<type>[scope][!]: <description>,type 取自 11 种(feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert)。
  • commitlint:在 conventional 基础上扩展 type(额外支持 wip、init、update、remove、security),并额外校验主题不以大写字母开头、不以句点结尾。
quicommit config set commit.format conventional
quicommit config set-commit-format commitlint
quicommit config set commit.auto_generate false

3.6 标签配置([tag])

键 类型 默认值 说明
version_prefix string "v" tag 版本前缀,如 v1.2.3
auto_generate 布尔 true 是否默认用 AI 生成 tag message
quicommit config set tag.version_prefix v
quicommit config set-version-prefix v

3.7 变更日志配置([changelog])

键 类型 默认值 说明
path string "CHANGELOG.md" 变更日志文件路径
auto_generate 布尔 true 是否默认用 AI 生成变更日志(--no-generate 可临时关闭,改用模版)
quicommit config set changelog.path CHANGELOG.md
quicommit config set-changelog-path CHANGELOG.md

3.8 语言配置([language])

键 类型 默认值 说明
output_language string "en" 界面/生成文案语言
keep_types_english 布尔 true 提交类型(feat、fix…)是否保持英文
keep_changelog_types_english 布尔 true 变更日志分类(Added、Fixed…)是否保持英文

支持的语言代码:en、zh(含 zh-cn / zh-tw)、ja、ko、es、fr、de(也接受 english、chinese 等全称)。无效代码会静默回退为英文。

quicommit config set-language zh          # 省略参数则交互式选择
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])

键 类型 默认值 说明
emoji 布尔 true 是否显示 ✓ / ✗ / ⚠ / → 等装饰符号
quicommit config set output.emoji false

命令行覆盖:--no-color 会同时关闭颜色与装饰;--emoji / --no-emoji 单独控制装饰。


4. 配置命令参考(quicommit config)

别名:quicommit cfg。不带子命令时等价于 config show。

子命令 说明
config show 汇总展示当前配置(通用 / LLM / 提交 / 标签 / 语言 / 变更日志 / 安全)
config path 打印配置文件路径
config edit 用 $EDITOR(或 $VISUAL)打开配置文件
config get <key> 读取单个配置项
config set <key> <value> 写入单个配置项(见下方键表)
config set-llm [provider] 交互式配置 LLM;可带 --model / --base-url / --api-key
config set-api-key [key] 设置当前 provider 的 API Key(省略则隐藏输入)
config delete-api-key 从当前存储方式中删除 API Key
config set-commit-format <fmt> 设置 conventional / commitlint
config set-version-prefix <prefix> 设置 tag 版本前缀
config set-changelog-path <path> 设置变更日志路径
config set-language [code] 设置输出语言(省略则交互式选择)
config set-keep-types-english <bool> 提交类型是否保持英文
config set-keep-changelog-types-english <bool> 变更日志分类是否保持英文
config list-models 按当前 provider 列出示例/已安装模型
config test-llm 发送一次测试请求,验证 provider 连通性
config check-keyring 检查密钥环可用性与相关环境变量
config export -o <file> [--password] 导出配置(可选加密)
config import -i <file> [--password] 导入配置
config reset [--force] 重置为默认配置

config set / config get 支持的键

键 取值
llm.provider ollama / openai / anthropic / kimi / deepseek / openrouter
llm.model 任意模型名
llm.base_url URL
llm.max_tokens 整数
llm.temperature 浮点
llm.timeout 整数(秒)
llm.thinking_enabled true / false
llm.thinking_budget_tokens 整数
llm.api_key_storage keyring / config / environment
commit.format conventional / commitlint
commit.auto_generate true / false
tag.version_prefix 字符串
tag.auto_generate true / false
changelog.path 路径字符串
changelog.auto_generate true / false
language.output_language 语言代码
language.keep_types_english true / false
language.keep_changelog_types_english true / false
output.emoji true / false

config set 只接受上表键名,其他键会报「未知配置键」。 API Key 不在其中——请用 config set-api-key / config delete-api-key。 布尔键只接受字面 true / false。


5. 身份配置命令参考(quicommit profile)

别名:quicommit p。不带子命令时等价于 profile list。

子命令 说明
profile add 交互式新建 profile(名称 / 用户名 / 邮箱 / 描述 / 工作标记 / SSH / GPG / 令牌)
profile list 列出所有 profile(默认项标 ●)
profile show [name] 展示当前仓库 Git 配置、匹配到的 profile 及详情
profile edit <name> 交互式编辑,含 SSH / GPG / 签名偏好 / 令牌子菜单
profile copy <from> <to> 复制 profile(不复制使用统计)
profile remove <name> 删除 profile(同时清理其密钥环 PAT)
profile set-default <name> 设置默认 profile
profile set-repo <name> 为当前仓库记录映射并立即应用
profile switch 交互式切换默认 profile,可选是否应用到当前仓库
profile apply [name] [--global] 把 profile(默认取 default)应用到当前仓库或全局 Git 配置
profile check [name] 对比 profile 与当前仓库 Git 配置的差异
profile stats [name] 查看使用统计
profile token add <profile> <service> 添加服务令牌(存入密钥环)
profile token remove <profile> <service> 移除服务令牌
profile token list <profile> 列出令牌及其存储状态

6. 令牌与凭据

PAT(Personal Access Token)

PAT 用于把私有仓库推送到 GitHub / GitLab 等平台,按 profile + 服务名 维度存入系统密钥环(config.toml 中只记录元信息如类型、描述、是否已存储)。

quicommit profile token add personal github
quicommit profile token list personal
quicommit profile token remove personal github

服务名可自由填写(github、gitlab、bitbucket 等)。

Git Credential Helper

QuiCommit 可作为 Git 凭据助手,注册后 Git 推送时会自动向它索取 PAT:

git config --global credential.helper quicommit
# 或限定主机

git config --global credential.https://github.com.helper quicommit

credential get|store|erase 由 Git 自动调用,命令隐藏在 --help 之外。删除已存凭据:

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

导入导出与备份

# 明文导出(不含密钥环中的 PAT)
quicommit config export -o config-backup.toml

# 加密导出(把 profile 的 PAT 一并加密打包)
quicommit config export -o config-backup.enc --password

# 导入
quicommit config import -i config-backup.toml
quicommit config import -i config-backup.enc --password

加密导出使用 AES-GCM + Argon2;导出文件以 ENCRYPTED: 前缀标识。若目标配置含有 PAT 却未启用加密,导入/导出会给出明文告警。


7. 环境变量

变量 说明
QUICOMMIT_CONFIG 配置文件路径(等价于 -c/--config)
QUICOMMIT_API_KEY 任意 provider 的 API Key,进程内始终优先于密钥环与配置文件
QUICOMMIT_<PROVIDER>_API_KEY provider 专属 API Key(如 QUICOMMIT_OPENAI_API_KEY)。交互式 init 会检测它,config check-keyring 会展示它
EDITOR / VISUAL config edit 使用的编辑器(EDITOR 优先)
NO_COLOR 设置任意值即关闭彩色与 Emoji 装饰
RUST_LOG 覆盖 -v 的日志过滤,如 RUST_LOG=debug

注意:真正参与生成请求的 Key 解析路径是 QUICOMMIT_API_KEY → 密钥环 →(api_key_storage = "config" 时)配置文件。 provider 专属的 QUICOMMIT_<PROVIDER>_API_KEY 目前仅用于 init 的检测与 config check-keyring 的展示;若要让它生效参与生成,请改设 QUICOMMIT_API_KEY。


8. 全局选项

所有子命令共享以下全局选项:

选项 说明
-v, --verbose(可叠加) -v info、-vv debug、-vvv trace
-c, --config <PATH> 配置文件路径
--no-color 关闭颜色与 Emoji 装饰(最高优先级)
--emoji / --no-emoji 强制开启/关闭 Emoji 装饰,覆盖 output.emoji

9. 完整配置示例

version = "1"
default_profile = "personal"

# ── LLM ─────────────────────────────────────────────────────────────
[llm]
provider = "deepseek"
model = "deepseek-v4-flash"
# base_url = "https://api.deepseek.com"   # 省略则用 provider 默认
max_tokens = 500
temperature = 0.6
timeout = 30
api_key_storage = "keyring"
thinking_enabled = false
# thinking_budget_tokens = 1024           # 仅 Anthropic 使用

# ── 提交 / 标签 / 变更日志 ──────────────────────────────────────────
[commit]
format = "conventional"
auto_generate = true

[tag]
version_prefix = "v"
auto_generate = true

[changelog]
path = "CHANGELOG.md"
auto_generate = true

# ── 语言与输出 ──────────────────────────────────────────────────────
[language]
output_language = "zh"
keep_types_english = true
keep_changelog_types_english = true

[output]
emoji = true

# ── 个人身份 ────────────────────────────────────────────────────────
[profiles.personal]
name = "personal"
user_name = "Your Name"
user_email = "you@example.com"
description = "个人项目"
is_work = false

[profiles.personal.settings]
auto_sign_commits = false
auto_sign_tags = false
repo_patterns = []

# ── 工作身份(含 SSH + GPG) ───────────────────────────────────────
[profiles.work]
name = "work"
user_name = "Your Name"
user_email = "you@company.com"
description = "工作项目"
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_profiles]
"/home/user/work/project" = "work"
"/home/user/personal/project" = "personal"

10. 常见场景配方

用本地 Ollama(无需 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          # 隐藏输入
# 或一次性:quicommit config set-llm deepseek --api-key <KEY>

工作 / 个人双身份

quicommit profile add                 # 建 personal
quicommit profile add                 # 再建 work(可配 SSH/GPG)
quicommit profile set-default personal

cd ~/work/project
quicommit profile set-repo work       # 记录映射并立即应用到本仓库
quicommit profile check work          # 校验是否与仓库 Git 配置一致

在 CI 中使用(无密钥环)

export QUICOMMIT_API_KEY=<KEY>        # 环境变量始终优先
export QUICOMMIT_CONFIG=./ci-config.toml
quicommit commit --yes

启用思考模式

# 仅本次提交
quicommit commit --think

# 全局默认开启(对 deepseek/kimi/anthropic/openai 生效)
quicommit config set llm.thinking_enabled true

Linux 无桌面环境(无 Secret Service)

# 方案一:改用环境变量
export QUICOMMIT_API_KEY=<KEY>

# 方案二:改存配置文件(明文,注意权限)
quicommit config set llm.api_key_storage config
quicommit config set-api-key

11. 故障排除

配置损坏或旧版本不兼容

quicommit config reset --force        # 重置为默认
quicommit init                        # 重新配置

API Key 相关报错

quicommit config check-keyring        # 确认密钥环是否可用、环境变量是否被识别
quicommit config show                 # 确认 provider 与 Key 掩码状态
quicommit config test-llm             # 端到端连通性
  • 「keyring is not available」:系统无 Secret Service(常见于无桌面的 Linux)。改用环境变量或 api_key_storage = config。
  • 「API key not configured」:set-api-key 未生效或环境变量未设置。
  • provider 报「not available」:多为 base_url 或凭据问题。DeepSeek 的默认地址是 https://api.deepseek.com(不带 /v1);若历史配置里显式写过 /v1 导致校验失败,请重新执行 quicommit config set-llm deepseek。

改了配置但行为没变

  • 确认改的是生效的配置文件:quicommit config path(注意 -c / QUICOMMIT_CONFIG 可能改变了路径)。
  • 检查全局选项是否覆盖了配置:--emoji、--no-emoji、--think。
  • 检查环境变量优先级:QUICOMMIT_API_KEY、RUST_LOG。

打开配置文件

quicommit config edit                 # 使用 $EDITOR / $VISUAL
quicommit config show                 # 只读查看