# GritQL — Declarative Code Rewrite CLI

> GritQL is a declarative language + CLI for searching and rewriting codebases with snippet-like patterns, making large refactors repeatable and reviewable.

## Install

Copy the content below into your project:

## Quick Use

1. Install the CLI:
   ```bash
   curl -fsSL https://docs.grit.io/install | bash
   ```
2. Find patterns:
   ```bash
   grit apply '`console.log($_)`'
   ```
3. Rewrite safely (start in a branch) and re-run until the diff is clean.

## Intro

GritQL is a declarative language + CLI for searching and rewriting codebases with snippet-like patterns, making large refactors repeatable and reviewable.

- **Best for:** teams doing recurring migrations (logging, API renames, lint fixes) across 10k–10M+ LOC repos
- **Works with:** polyglot repos (TS/Python/Go/etc.), CI-driven codemods, branch-based review workflows
- **Setup time:** 5 minutes

## Practical Notes

- Designed for scale: README claims it can handle 10M+ line repositories
- Reuse library patterns: supports 200+ shared patterns via a built-in module system (README)

## A Practical Refactor Loop for Agents

If you’re using coding agents, the bottleneck is often “how do we apply the same change consistently across many files?”

GritQL helps by making the change **declarative**:

1. Start with a search-only pattern to learn the surface area.
2. Add a rewrite (`=>`) once you’re confident the match is precise.
3. Run on a small folder first, then the whole repo.
4. Review the diff like any other migration (tests + lint + code review).

Example rewrite from the README:

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

If the repo is large, treat the migration as a batch job: run it once in CI, then keep it as a reusable “codemod” command for future consistency.

### FAQ

**Q: Do I need to learn ASTs?**
A: No. The README emphasizes snippet-like patterns as valid queries without deep AST knowledge.

**Q: Is it only for JavaScript?**
A: No. It supports many target languages (TS/Python/Go/etc.) via its language support matrix.

**Q: How do I keep it safe?**
A: Run in a branch, start small, and use CI tests + code review like any refactor.

## Source & Thanks

> Source: https://github.com/biomejs/gritql
> License: MIT
> GitHub stars: 4,493 · forks: 121

---

<!-- ZH -->

## 快速使用

1. 安装 CLI：
   ```bash
   curl -fsSL https://docs.grit.io/install | bash
   ```
2. 用模式搜索：
   ```bash
   grit apply '`console.log($_)`'
   ```
3. 在分支里先小范围试跑，确认 diff 符合预期后再扩大范围。

## 简介

GritQL 是一套“像写代码片段一样写规则”的声明式查询语言 + CLI，可在大仓库里可重复地搜索与重写代码，并把迁移输出为可审查、可回滚的 diff，适合团队长期维护 codemod 与迁移规则库。

- **适合谁：** 需要反复做迁移（日志替换、API 改名、批量修复）且仓库规模很大的团队
- **可搭配：** 多语言仓库（TS/Python/Go 等）、CI codemod、基于分支的 code review
- **准备时间：** 5 分钟

## 实战建议

- 面向大仓库：README 提到可扩展到 10M+ 行代码级别
- 可复用规则：内置模块系统并提供 200+ 标准 patterns（README）

## 适合 Agent 的“批量改代码”闭环

在 Agent 编码场景里，最容易出问题的是：同一种改法在不同文件里不一致，导致 review 很痛苦。

GritQL 的关键价值在于把改动变成**声明式规则**：

1. 先用“只搜索不改写”的模式摸清影响面；
2. 再加上 `=>` 规则做重写；
3. 先在小目录试跑，再扩大到全仓；
4. 最后像正常迁移一样走测试、lint 和 code review。

README 给了一个典型例子：

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

如果仓库很大，把它当成 CI 批处理任务更稳：一次生成可审查 diff，然后把规则沉淀为以后可复用的 codemod。

### FAQ

**一定要懂 AST 吗？**
答：不需要，README 强调“像写代码片段一样”的模式也能作为查询。

**只能改 JavaScript 吗？**
答：不是，它支持多种目标语言（TS/Python/Go 等），以官方支持矩阵为准。

**怎么保证安全？**
答：在分支里跑、先小后大、最后用测试与 code review 把关。

## 来源与感谢

> Source: https://github.com/biomejs/gritql
> License: MIT
> GitHub stars: 4,493 · forks: 121


---
Source: https://tokrepo.com/en/workflows/gritql-declarative-code-rewrite-cli
Author: Script Depot