docs.grit.io

Grit是什么网站?

Grit 是一个用声明式查询语言 GritQL 搜索和批量改写源代码的网站，核心用途是把“找代码、改代码”写成可复用、可执行的规则，而不是靠人工逐处替换。

它的功能用途

• 代码搜索与自动修复：用代码片段本身当查询，反引号包住要匹配的代码，$变量 代表可变部分。例如 `console.log($msg)` => `winston.log($msg)` 表示把所有 console.log 调用替换成 winston.log。
• 自定义 lint 规则：把模式保存成团队级 lint，用 where 条件排除特殊情况，比如跳过测试文件中的 console.log。
• 大规模迁移：资料称可借助 Rust 和查询优化处理 1000 万行以上的仓库，适合 API 迁移、框架升级、依赖升级等场景。
• 多语言覆盖：支持 JavaScript/TypeScript、Python、JSON、Java、Terraform、Solidity、CSS、Markdown、YAML、Rust、Go、SQL。
• 模式复用：内置模块系统，可访问 200 多个标准模式，也能分享自己写的模式。

谁在什么情况下用它

• 团队要统一代码规范，但现成 lint 规则表达不了自己的特殊约束。
• 做框架或 API 升级，需要在上百万行代码里批量改调用方式。
• 想系统性地清理某类写法，并让修复规则可以重复执行、进 CI。

选择时的注意点

Grit 的侧重点是“声明式改写 + 自动修复”，适合把迁移和规范沉淀成规则。如果只是临时搜几处代码，普通编辑器搜索更直接；如果要做跨仓库、可复用的批量改造，GritQL 的表达能力和模块复用更合适。下一步可从它的 CLI Quickstart 和交互式教程入手，先写一条替换规则在小型仓库验证。

GritQL 如何用反引号写一个简单的搜索替换查询?

在 GritQL 里，最简单的搜索替换就是把“原代码片段”和“目标代码片段”各用一对反引号包起来，中间用 => 连接，再交给 grit apply 执行。代码片段里想匹配任意内容时，用 $变量名 这样的元变量占位。

基本写法

grit apply '`console.log($msg)` => `winston.log($msg)`'

这条查询会找到所有 console.log(...) 调用，把函数名换成 winston.log，括号里的参数原样保留。$msg 是元变量，匹配到的内容在替换结果里会被复用。

加条件收窄范围

如果只想改一部分调用，可以在替换规则后加 where 子句。例如排除测试文件里的调用：

`console.log($msg)` => `winston.log($msg)` where {
  $msg <: not within or { `it($_, $_)`, `test($_, $_)` }
}

where 用来表达“在什么情况下才替换”，适合把批量改写限制在业务代码里，避免误改测试。

使用要点

• 反引号里的代码片段本身就是合法查询，不需要先学 AST 结构；想匹配更复杂的结构时再逐步加 where、模式修饰符等。
• 元变量 $msg 在搜索侧和替换侧同名，替换时自动带入匹配内容；$_ 表示不关心该位置的具体内容。
• 这类查询可以保存为自定义 lint 规则，配合自动修复在团队里持续执行，而不只是一次性脚本。
• 同一套写法覆盖 JavaScript/TypeScript、Python、Java、Go、Rust、SQL、Terraform、CSS、Markdown、YAML 等语言，跨语言迁移时不必换工具。

适合谁用

需要在几十万到上百万行代码里做 API 迁移、依赖升级或统一代码风格的团队，可以直接从一条反引号查询开始，再逐步加条件；个人项目里做一次性批量替换也同样适用。

如何把 GritQL 模式保存为自定义 lint 并排除特定代码场景?

在 GritQL 里，把模式保存为自定义 lint 的核心做法是：写一条“匹配 → 改写”的规则，把需要排除的场景放进 where 子句，然后用 CLI 应用或保存为可复用的模式。

基本写法

以资料中的示例为例，把 console.log 改写为 winston.log，并排除测试文件里的调用：

`console.log($msg)` => `winston.log($msg)` where {
  $msg <: not within or { `it($_, $_)`, `test($_, $_)` }
}

• 反引号里的代码片段就是匹配模式，$msg 是元变量，能捕获任意参数。
• => 后面是自动修复后的目标代码，所以这条规则既是 lint 也是 auto-fix。
• where 子句用来加条件，not within or { ... } 表示“不位于 it(...) 或 test(...) 调用内部”，从而排除测试场景。

保存与复用

资料提到 Grit 有内置模块系统，可访问 200+ 标准模式，也能分享自己的模式。实际做法是把规则写入模式文件（如 .grit/patterns/ 下的 .grit 文件），之后通过 grit apply 或 CI 集成重复使用；需要团队共享时，按模块方式引入或发布。

排除场景的常见写法

下一步

先写最小规则，用 grit apply 在单个文件上验证匹配范围；确认排除条件生效后，再接入 CI 作为持续 lint。资料中的 Interactive Tutorial 和 Pattern Library 可用于对照标准模式的写法。

Grit 支持哪些编程语言的代码搜索与改写?

Grit 的 GritQL 支持以下语言的代码搜索与改写：JavaScript/TypeScript、Python、JSON、Java、Terraform、Solidity、CSS、Markdown、YAML、Rust、Go、SQL。

各语言的使用场景

• JavaScript/TypeScript、Python、Java、Go、Rust：适合做大规模 API 迁移、框架升级和团队自定义 lint。例如把 console.log($msg) 批量改成 winston.log($msg)，并用 where 条件排除测试文件中的调用。
• JSON、YAML、Terraform：适合配置文件和基础设施代码的批量改写，比如统一字段名、调整资源定义。
• CSS、Markdown：适合样式和文档的批量整理，例如统一选择器写法或批量替换文档片段。
• Solidity、SQL：适合合约和查询语句的模式化检查与改写。

选择条件

如果项目以 JavaScript/TypeScript 为主，GritQL 的示例和内置模式覆盖最直接；跨多种语言维护仓库时，可以用同一套声明式写法分别处理，不必为每种语言换工具。需要批量改写并附带自动修复规则时，优先看目标语言是否在上面的列表内。

如何在 VS Code 中使用 Grit 来搜索或修改代码?

Grit 在 VS Code 中通过官方扩展使用：安装扩展后，在编辑器里用 GritQL 模式搜索代码，或直接把匹配到的结构改写成新写法。GritQL 的规则是“任意代码片段即查询”，例如用反引号写 `console.log($msg)` => `winston.log($msg)`，就能把匹配的 console.log 调用替换成 winston.log，变量部分用 $msg 这类元变量保持不变。

在 VS Code 里的典型用法

• 搜索：写一个代码片段作为模式，扩展会定位所有匹配位置，不需要先理解 AST 结构。
• 修改：在模式后加 => 和目标写法，预览后应用替换；适合批量改 API 调用、统一日志写法等。
• 限定范围：用 where 条件排除特定场景，例如官方示例在替换 console.log 时排除 it(...)、test(...) 测试块内的调用。
• 复用规则：Grit 内置 200 多个标准模式，也可保存自己的模式作为自定义 lint 强制执行。

适合什么场景

需要跨大量文件统一改法时最有用，例如迁移框架/API、升级依赖时处理破坏性变更、落实团队特有的代码规范。GritQL 支持 JavaScript/TypeScript、Python、JSON、Java、Terraform、Solidity、CSS、Markdown、YAML、Rust、Go、SQL 等语言，同一套写法可覆盖多语言仓库。

选择条件

如果只是单文件内简单文本替换，VS Code 自带查找替换更直接；如果要按代码结构匹配、带条件排除、并希望规则能保存复用或在 CI 中执行，GritQL 更合适。建议先在 VS Code 扩展里用小范围文件试跑一条改写规则，确认匹配范围后再扩大应用。

如何把 GritQL 集成到持续集成流程中自动修复代码问题?

GritQL 本身是声明式代码搜索与改写语言，集成到 CI 的关键是把“查询 + 自动修复”变成 CI 里可重复执行的一步：用 Grit CLI 在流水线中运行已保存的模式，命中即改写文件，再让差异检查决定是否阻断合并。文档明确 GritQL 内置 auto-fix 规则，适合“发现问题就顺手改掉”的流水线场景。

在 CI 中落地的典型流程

1. 把规则存成可复用模式：在仓库里维护 GritQL 模式文件（例如把 console.log($msg) 改为 winston.log($msg)），并用 where 子句排除测试文件等误报场景。文档示例用 not within 排除 it(...)、test(...) 上下文，这类条件适合直接放进 CI 规则。
2. CI 中执行 CLI：在流水线里安装并运行 Grit CLI，对目标目录执行已保存模式；GritQL 支持 JavaScript/TypeScript、Python、Java、Go、Rust、SQL、Terraform、YAML、Markdown 等多种语言，可按仓库技术栈选择。
3. 用差异决定结果：运行后检查工作区是否有改动。有改动说明存在可自动修复的问题，可让 CI 失败并提示提交修复，或把改动作为补丁产物输出；无改动则通过。
4. 把“不可自动修复”的情况留给 lint 报告：GritQL 也用于自定义 lint，团队特定规范可以先以报告形式上线，稳定后再加 auto-fix 规则。

适合谁、什么情况下用

• 大规模迁移：API 或框架升级涉及几十万到百万行代码时，用 GritQL 在 CI 中批量改写，比人工逐文件修改更一致。文档称其可扩展到 1000 万行以上仓库。
• 团队规范 enforcement：把“禁止在测试里用 console.log”这类团队约定写成模式，CI 每次检查并自动修复。
• 依赖升级处理 breaking change：升级依赖后，用模式统一替换旧调用方式。

选择条件

下一步动作

先在本地用 CLI 跑通一条模式，确认改写结果符合预期；再把该模式加入 CI 脚本，并设置“有 diff 即失败”的门槛。规则稳定后，逐步把团队 lint 规则迁移为带 auto-fix 的 GritQL 模式。