配置¶

linthis 可以通过配置文件、CLI 参数或两者结合进行配置。

配置文件¶

项目配置¶

使用 linthis init 创建配置文件：

linthis init

这会在项目根目录创建 .linthis/config.toml：

# 指定要检查的语言（省略则自动检测）
languages = ["rust", "python", "javascript"]

# 排除文件和目录
excludes = [
    "target/**",
    "node_modules/**",
    "*.generated.rs",
    "dist/**"
]

# 最大圈复杂度
max_complexity = 20

# 格式化预设
preset = "google"  # 选项：google、airbnb、standard

# 配置插件
[plugins]
sources = [
    { name = "official" },
    { name = "myplugin", url = "https://github.com/user/plugin.git", ref = "main" }
]

# 语言特定配置
# [rust]
# max_complexity = 15

# [python]
# excludes = ["*_test.py"]

全局配置¶

全局配置位于 ~/.linthis/config.toml，格式与项目配置相同。

配置优先级¶

配置合并优先级（从高到低）：

CLI 参数：--option value
项目配置：.linthis/config.toml
全局配置：~/.linthis/config.toml
内置默认值

对于工具特定的配置文件（ruff.toml、.eslintrc.js 等），优先级如下：

本地手动配置（最高）- 项目中的 ruff.toml、pyproject.toml、.eslintrc.js
CLI 插件配置 - 来自 --use-plugin 选项
项目插件配置 - 来自 .linthis/config.toml 的 plugins 部分
全局插件配置 - 来自 ~/.linthis/config.toml 的 plugins
工具默认值（最低）

配置管理命令¶

数组字段操作¶

支持的数组字段：includes、excludes、languages

# 添加值
linthis config add includes "src/**"
linthis config add excludes "*.log"
linthis config add languages "rust"

# 添加到全局配置
linthis config add -g includes "lib/**"

# 移除值
linthis config remove excludes "*.log"

# 清空字段
linthis config clear languages

标量字段操作¶

支持的标量字段：max_complexity、preset、verbose

# 设置值
linthis config set max_complexity 15
linthis config set preset google

# 设置全局配置
linthis config set -g max_complexity 20

# 取消设置
linthis config unset max_complexity

查询操作¶

# 获取单个字段
linthis config get includes
linthis config get max_complexity

# 列出所有配置
linthis config list
linthis config list -g  # 全局配置
linthis config list -v  # 详细模式（显示空字段）

配置迁移¶

linthis 可以迁移现有的 linter/formatter 配置：

# 自动检测并迁移所有配置
linthis config migrate

# 迁移特定工具
linthis config migrate --from eslint
linthis config migrate --from prettier
linthis config migrate --from black

# 预览更改
linthis config migrate --dry-run

# 创建备份
linthis config migrate --backup

支持的工具¶

工具	检测文件
ESLint	`.eslintrc.js`、`.eslintrc.json`、`.eslintrc.yml`、`eslint.config.js`
Prettier	`.prettierrc`、`.prettierrc.json`、`.prettierrc.yml`、`prettier.config.js`
Black	`pyproject.toml[tool.black]`
isort	`pyproject.toml[tool.isort]`

环境变量¶

`LINTHIS_SKIP` — 跳过指定 hook¶

git commit --no-verify 会一次跳过所有 hook。LINTHIS_SKIP 可以只跳过某个，其余照常运行。值以逗号分隔，大小写不敏感。

值	跳过的 hook
`check` 或 `pc`	pre-commit + post-commit（两者配对，一起跳）
`pre-commit`	只跳 pre-commit
`post-commit`	只跳 post-commit
`cmsg`、`cm` 或 `commit-msg`	commit-msg
`pp` 或 `pre-push`	pre-push
`all`	全部 hook

# 只跳过 commit-msg 正则校验，lint 仍然跑
LINTHIS_SKIP=cm git commit -m "WIP: 临时消息"

# 跳过 pre-commit 的 lint/security/complexity 以及 post-commit，但保留 commit-msg
LINTHIS_SKIP=check git commit -m "feat: 快速保存"

# 同时跳过多个
LINTHIS_SKIP=cm,pp git push

未知 token 会报错且不跳过 —— 避免"以为跳了但其实没跳"。

`LINTHIS_SKIP_CHECKS` — 跳过具体的 check¶

用于在 hook（pre-commit / pre-push）内部跳过具体的 check。支持全名，也支持不少于 3 个字符的前缀（大小写不敏感）。

值	效果
`lin` 或 `lint`	跳过 lint 检查
`sec` 或 `security`	跳过 security (SAST) 检查
`com` 或 `complexity`	跳过 complexity 检查

# 跳过较慢的 complexity 检查
LINTHIS_SKIP_CHECKS=com git commit -m "fix: bug"

# 只跑 security（跳过 lint 和 complexity）
LINTHIS_SKIP_CHECKS=lin,com git commit -m "fix: bug"

少于 3 字符或无法匹配的 token 会打印警告并被忽略，其余依旧生效。

两个变量互相正交，可以同时用：

LINTHIS_SKIP=cm LINTHIS_SKIP_CHECKS=com git commit -m "WIP"

`LINTHIS_AGENT_MAX_AUTO_FIX` — 限制大规模 auto-fix¶

git-with-agent 类型的 hook 在 lint 失败时会调 AI agent（Claude / Codex / Gemini ...）自动修复。但当错误有成百上千个时，调用会阻塞几分钟并且看不到进度。

LINTHIS_AGENT_MAX_AUTO_FIX 给 errors + warnings 设置上限 —— 超过阈值则跳过 auto-fix，commit 快速失败并提示用交互式修复（agent 输出会实时流式打印）：

# 默认：errors+warnings > 100 时跳过 auto-fix
git commit -m "..."

# 临时提高阈值
LINTHIS_AGENT_MAX_AUTO_FIX=500 git commit -m "..."

# 完全关闭限制（不推荐 —— commit 可能长时间卡住）
LINTHIS_AGENT_MAX_AUTO_FIX=0 git commit -m "..."

当 hook 判定调 agent 时，agent 的输出会直接流式打到终端 —— 不再是只有 spinner 的"假死"。随时 Ctrl-C 取消。

对 Claude Code 和 CodeBuddy，linthis 会用 --output-format stream-json 启动它们，然后把事件流通过管道喂给 linthis agent-stream，逐行把每个 assistant 消息、工具调用（Edit /path/to/file、Bash cargo check 等）渲染成人类可读的输出。其他 provider（codex exec、cursor-agent chat、droid exec）本身就是流式的。

`.linthisignore`¶

项目根目录下的 .linthisignore 文件提供了一种无需编辑 config.toml 就能快速抑制 lint 问题的方式。支持两种条目类型：

# 从 lint 中排除文件（gitignore glob 语法）
vendor/**
*.generated.go

# 按代码禁用规则
rule:E501
rule:clippy::too_many_arguments
rule:linthis-complexity

使用 linthis ignore 命令管理条目：

linthis ignore add "vendor/**"
linthis ignore add "rule:E501"
linthis ignore remove "rule:E501"
linthis ignore list

在交互式修复模式（linthis fix）中，按 w 键可直接将当前问题的规则代码写入 .linthisignore。

详细文档见忽略规则。

下一步¶

忽略规则 - 用 .linthisignore 抑制问题
插件系统 - 共享配置
CLI 参考 - 所有命令选项

配置¶