# GritQL

> GritQL is a declarative query language for searching, linting, and modifying source code across multiple programming languages using pattern matching.

GritQL is a declarative query language built in Rust for searching and modifying source code at scale. Originally developed by Iuvo AI, Inc., the project was transferred to the Biome Developers and Contributors and is now maintained under the biomejs GitHub organization. It is released under the MIT license and is freely available as open-source software.

## What It Is

GritQL sits in the space between simple grep searches and full codemod programs. It lets developers write code search and transformation patterns using familiar code snippets rather than abstract syntax tree (AST) node names, making it accessible without deep compiler knowledge. The language supports large-scale migrations, custom linting, code quality improvements, and dependency upgrades across codebases with 10 million or more lines of code.

## How the Pattern Language Works

GritQL patterns are written by placing code snippets in backticks and using `$metavariables` as placeholders for variable parts. A rewrite is expressed with `=>`, and side conditions are added with `where` clauses. For example:

- Search: `` `console.log($msg)` ``
- Rewrite: `` `console.log($msg)` => `winston.log($msg)` ``
- Conditional exclusion: add `where { $msg <: not within or { \`it($_, $_)\`, \`test($_, $_)\` } }` to skip test files

Patterns can be saved to a `grit.yaml` configuration file and enforced as custom lint rules via `grit check`, which integrates into CI pipelines.

## Target Languages and Reuse

GritQL is designed to be language-agnostic once learned. The same query syntax works across JavaScript, TypeScript, Python, JSON, Java, Terraform, Solidity, CSS, Markdown, YAML, Rust, Go, and SQL. A built-in module system allows patterns to be shared and reused, and the project ships with 200+ standard patterns in a public standard library (`getgrit/stdlib`). Teams can also publish and import their own patterns.

## Architecture and Performance

The engine is written in Rust and uses tree-sitter for all language parsers, enabling query optimization that scales to repositories with tens of millions of lines. The README notes that rewrites across millions of lines can complete in seconds. This performance focus addresses a common pain point with existing codemod frameworks, where iterating on large transformations can be slow.

## Lineage and Current Status

The repository at `biomejs/gritql` reflects a transfer from the original `getgrit/gritql` repository after Iuvo AI, Inc. developed the initial codebase. The latest release is v0.0.3, published in March 2026, and the repository shows active maintenance with recent pushes in July 2026. The project has accumulated over 4,500 GitHub stars and 124 forks. Documentation, an interactive tutorial, a playground, and a VS Code extension guide are all available at docs.grit.io.

## Features
- Declarative pattern-based code search and rewriting
- Metavariable placeholders for flexible matching
- Where clauses for conditional pattern application
- Auto-fix rules for faster remediation
- 200+ standard patterns via built-in module system
- Custom lint enforcement via grit check
- CI integration support
- Supports 12+ target languages (JS, TS, Python, Java, Rust, Go, SQL, etc.)
- Scales to 10M+ line repositories
- VS Code extension guide
- Interactive playground
- Pattern sharing and publishing

## Integrations
VS Code, CI/CD pipelines, tree-sitter, JavaScript, TypeScript, Python, Java, Terraform, Solidity, CSS, Markdown, YAML, Rust, Go, SQL, JSON

## Platforms
CLI, API, VSC_EXTENSION

## Pricing
Open Source

## Version
v0.0.3

## Links
- Website: https://docs.grit.io/
- Documentation: https://docs.grit.io/language/overview
- Repository: https://github.com/biomejs/gritql
- EveryDev.ai: https://www.everydev.ai/tools/gritql