I’m excited to open source GritQL, a Rust CLI for searching and transforming source code.

GritQL comes from my experiences with conducting large scale refactors and migrations.

Usually, I would start exploring a codebase with grep. This is easy to start with, but most migrations end up accumulating additional requirements like ensuring the right packages are imported and excluding cases which don’t have a viable migration path.

Eventually, to build a complex migration, I usually ended up having to write a full codemod program with a tool like jscodeshift. This comes with its own problems:

- Most of the exploratory work has to be abandoned as you figure out how to represent your original regex search as an AST. - Reading/writing a codemod requires mentally translating from AST names back to what source code actually looks like. - Performance is often an afterthought, so iterating on a large codemod can be painfully slow. - Codemod frameworks are language-specific, so if you’re hopping between multiple languages—or trying to migrate a shared API—you have to learn different tools.

GritQL is an attempt to develop a powerful middle ground: - Exploratory analysis is easy: just put a code snippet in backticks and use $metavariables for placeholders. - Incrementally add complexity by introducing side conditions with where clauses. - Reuse named patterns to avoid rebuilding queries, and use shared patterns from our standard library for common tasks like ensuring modules are imported. - Iterate on large codebases quickly: we use Rust for maximum performance

GritQL has already been used on thousands of repositories for complex migrations[1] but we're excited to collaborate more with the open source community.

[1] Ex. https://github.com/openai/openai-python/discussions/742