# biomejs/gritql

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/biomejs-gritql).**

4,406 stars · 121 forks · Rust · mit

## Links

- GitHub: https://github.com/biomejs/gritql
- Homepage: https://docs.grit.io/
- awesome-repositories: https://awesome-repositories.com/repository/biomejs-gritql.md

## Topics

`ast` `codemod` `javascript` `linter` `refactoring` `rust` `search` `tree-sitter`

## Description

GritQL is an AST-based code transformation engine and structural search tool. It uses a declarative query language to identify and rewrite source code patterns across multiple programming languages by matching abstract syntax tree nodes rather than literal text.

The system functions as an automated refactoring framework for large-scale migrations and API updates. It distinguishes itself by utilizing sequential transformation pipelines and reusable blueprints that can be synced between local environments and remote repositories.

The tool covers a broad range of capabilities including static analysis linting for continuous integration, multi-file analysis, and the ability to extend query logic via JavaScript predicates. It supports complex code manipulation through metavariable binding, recursive tree traversal, and the automated generation of new files.

Users can define and test rewrite patterns using Markdown documents or YAML files, which can be bundled with test cases to verify transformation accuracy.

## Tags

### Development Tools & Productivity

- [AST-Based Source Transformations](https://awesome-repositories.com/f/development-tools-productivity/ast-transformation-tools/ast-to-source-conversion/ast-based-source-transformations.md) — Searches and rewrites source code by matching abstract syntax tree nodes rather than literal text.
- [Source Code Rewriting](https://awesome-repositories.com/f/development-tools-productivity/ast-transformation-tools/ast-to-source-conversion/source-code-rewriting.md) — Transforms matched code nodes into a new form using a rewrite arrow and optional conditions. ([source](https://cdn.jsdelivr.net/gh/biomejs/gritql@main/README.md))
- [Automated Code Refactoring](https://awesome-repositories.com/f/development-tools-productivity/code-quality-analysis/static-analysis-engines/static-analysis-tools/code-analysis-and-transformation/automated-code-refactoring.md) — Applies sequential transformation pipelines and reusable blueprints for large-scale code changes.
- [Structural Search Engines](https://awesome-repositories.com/f/development-tools-productivity/code-quality-analysis/static-analysis-engines/static-analysis-tools/code-analysis-and-transformation/structural-search-engines.md) — Finds code patterns by their syntax tree structure, ignoring formatting differences for precise matching.
- [Codebase Search Engines](https://awesome-repositories.com/f/development-tools-productivity/developer-utilities-libraries/workflow-productivity-enhancers/developer-productivity-utilities/code-search-utilities/codebase-search-engines.md) — Processes millions of lines of code efficiently using a Rust-powered engine with query optimization. ([source](https://docs.grit.io/))
- [Metavariable Captures](https://awesome-repositories.com/f/development-tools-productivity/metavariable-captures.md) — Binds any part of a matched code snippet to a named metavariable for reuse in conditions or rewrites. ([source](https://docs.grit.io/tutorials/gritql))
- [Remote Pattern Imports](https://awesome-repositories.com/f/development-tools-productivity/remote-pattern-imports.md) — Loads and applies code transformation rules from external Git repositories as dependencies. ([source](https://docs.grit.io/guides/config))
- [Reusable Query Patterns](https://awesome-repositories.com/f/development-tools-productivity/reusable-query-patterns.md) — Declares named patterns that accept parameters, bridging scope boundaries for shared variables while keeping others local. ([source](https://docs.grit.io/language/bubble))
- [Sequential Transformation Pipelines](https://awesome-repositories.com/f/development-tools-productivity/sequential-execution-engines/sequential-transformation-pipelines.md) — Applies multiple rewrite rules in a defined sequence, enabling complex multi-step code migrations.
- [Shared Pattern Repositories](https://awesome-repositories.com/f/development-tools-productivity/shared-pattern-repositories.md) — References patterns from external repositories by prefixing the pattern name with the repository name and a hash. ([source](https://docs.grit.io/guides/sharing))
- [AST Pattern Matchers](https://awesome-repositories.com/f/development-tools-productivity/source-code-search-engines/ast-pattern-matchers.md) — Provides AST-based pattern matching for precise, structure-aware code searches across multiple languages. ([source](https://docs.grit.io/language))
- [Named Pattern Invocations](https://awesome-repositories.com/f/development-tools-productivity/text-pattern-search/named-pattern-invocations.md) — Provides a declarative query language where named patterns can be invoked and composed for code search and transformation. ([source](https://docs.grit.io/tutorials/gritql))
- [Custom Lint Rule Definitions](https://awesome-repositories.com/f/development-tools-productivity/code-quality-analysis/static-analysis-engines/static-analysis-tools/static-analysis-rules/framework-linting-rules/core-rule-extensions/custom-lint-rule-plugins/custom-lint-rule-definitions.md) — Applies saved patterns as project-specific linting rules that can exclude certain code contexts. ([source](https://docs.grit.io/))
- [Prebuilt Pattern Libraries](https://awesome-repositories.com/f/development-tools-productivity/coding-pattern-libraries/prebuilt-pattern-libraries.md) — Runs a pre-built pattern from the standard library to automatically modify source code in the current directory. ([source](https://docs.grit.io/cli/quickstart))
- [Analysis Suppressions](https://awesome-repositories.com/f/development-tools-productivity/formatting-suppression/analysis-suppressions.md) — Provides inline comment directives and configuration to suppress specific analysis results on targeted lines. ([source](https://docs.grit.io/guides/config))
- [Pattern Publishing to Git](https://awesome-repositories.com/f/development-tools-productivity/git-repository-integrators/git-repository-integrators/pattern-publishing-to-git.md) — Publishes patterns by pushing them to a Git repository, making them reusable across projects. ([source](https://docs.grit.io/guides/sharing))
- [Pattern References by Repository and Hash](https://awesome-repositories.com/f/development-tools-productivity/remote-pattern-imports/pattern-references-by-repository-and-hash.md) — References patterns from remote Git repositories by prefixing with repository name and hash. ([source](https://docs.grit.io/guides/sharing))

### Software Engineering & Architecture

- [Code Transformation Engines](https://awesome-repositories.com/f/software-engineering-architecture/code-transformation-engines.md) — Provides a declarative code transformation engine that rewrites matched patterns using rule-based syntax with optional conditions. ([source](https://docs.grit.io/))
- [AST Querying](https://awesome-repositories.com/f/software-engineering-architecture/abstract-syntax-tree-parsing/ast-querying.md) — Matches and rewrites source code by querying abstract syntax tree nodes instead of literal text patterns.
- [Pattern-Based Code Manipulation](https://awesome-repositories.com/f/software-engineering-architecture/coding-patterns/pattern-based-code-manipulation.md) — Provides declarative pattern-based code manipulation that replaces matched AST nodes with new code snippets. ([source](https://docs.grit.io/))
- [Metavariable Pattern Matching](https://awesome-repositories.com/f/software-engineering-architecture/coding-patterns/pattern-based-code-manipulation/metavariable-pattern-matching.md) — Matches code patterns using backticks and metavariables to find specific syntax structures across files. ([source](https://docs.grit.io/))
- [Large-Scale Code Migrations](https://awesome-repositories.com/f/software-engineering-architecture/large-scale-code-migrations.md) — Automates large-scale API, framework, or dependency migrations across millions of lines of code. ([source](https://docs.grit.io/))
- [Custom Pattern Applications](https://awesome-repositories.com/f/software-engineering-architecture/anti-patterns/sql-anti-pattern-analyzers/pattern-transformers/custom-pattern-applications.md) — Runs a user-written pattern against the current directory to search or transform source code. ([source](https://docs.grit.io/cli/quickstart))
- [Pattern Metadata Headers](https://awesome-repositories.com/f/software-engineering-architecture/application-lifecycle-management/configuration-management/configuration-formats-and-schemas/configuration-formats/yaml-frontmatter-configurations/pattern-metadata-headers.md) — Configures optional enforcement level and tags for a pattern using YAML frontmatter in the Markdown file. ([source](https://docs.grit.io/guides/authoring))
- [Pattern Validation Samples](https://awesome-repositories.com/f/software-engineering-architecture/application-lifecycle-management/configuration-management/configuration-formats-and-schemas/yaml-configuration-files/pattern-validation-samples.md) — Specifies input and expected output samples directly in the configuration file for pattern validation. ([source](https://docs.grit.io/guides/testing))
- [Codebase Pattern Enforcements](https://awesome-repositories.com/f/software-engineering-architecture/codebase-pattern-enforcements.md) — Overrides the default enforcement level for imported patterns by specifying a level like error or warn. ([source](https://docs.grit.io/guides/sharing))
- [Conditional Rewrite Rules](https://awesome-repositories.com/f/software-engineering-architecture/coding-patterns/pattern-based-code-manipulation/boolean-rewrite-constraints/conditional-rewrite-rules.md) — Supports conditional rewrites where a transformation is applied only when a metavariable matches a specified condition. ([source](https://docs.grit.io/language/conditions))
- [Auto-Fix Engines](https://awesome-repositories.com/f/software-engineering-architecture/configuration-driven-rule-engines/plugin-based-rule-engines/auto-fix-engines.md) — Includes automatic remediation rules within queries so matching code is fixed without manual intervention. ([source](https://docs.grit.io/))
- [Negative Conditional Logic](https://awesome-repositories.com/f/software-engineering-architecture/negative-conditional-logic.md) — Inverts a condition so the pattern matches only when the condition is false, similar to a logical NOT. ([source](https://docs.grit.io/language/conditions))
- [Pattern Execution in CI](https://awesome-repositories.com/f/software-engineering-architecture/pattern-based-ci-enforcement/pattern-execution-in-ci.md) — Runs configured patterns as automated checks on every commit, failing the pipeline when new errors are introduced. ([source](https://docs.grit.io/guides/ci))
- [Pattern Severity Configurations](https://awesome-repositories.com/f/software-engineering-architecture/violation-reporters/violation-severity-management/pattern-severity-configurations.md) — Marks patterns as warnings or errors so CI checks fail only on new violations, allowing incremental fixes without breaking the build. ([source](https://docs.grit.io/guides/ci))
- [Pattern Severity Overrides](https://awesome-repositories.com/f/software-engineering-architecture/warning-issuance-systems/warning-threshold-enforcers/pattern-severity-overrides.md) — Overrides the default enforcement level for imported patterns by specifying a level like error or warn. ([source](https://docs.grit.io/guides/sharing))

### Part of an Awesome List

- [Named Pattern Definitions](https://awesome-repositories.com/f/awesome-lists/devtools/pattern-matching/code-naming-patterns/named-pattern-definitions.md) — Defines reusable named patterns with parameters that can be invoked by other patterns for matching or transformation. ([source](https://docs.grit.io/guides/patterns))
- [Named Rewrite Rules](https://awesome-repositories.com/f/awesome-lists/devtools/pattern-matching/code-naming-patterns/named-rewrite-rules.md) — Defines named, reusable search-and-rewrite rules with optional metadata like title, description, and enforcement level. ([source](https://docs.grit.io/guides/config))
- [Pattern File Imports](https://awesome-repositories.com/f/awesome-lists/ai/document-q-a/pattern-file-imports.md) — Loads a pattern definition from a Markdown or pattern file located anywhere in the repository. ([source](https://docs.grit.io/guides/config))
- [Pattern Bundling Formats](https://awesome-repositories.com/f/awesome-lists/devtools/linting-and-formatting/markdown-formatting/pattern-bundling-formats.md) — Provides a markdown-bundled format that packages queries, documentation, and test cases into reusable pattern files.
- [Language Variant Support](https://awesome-repositories.com/f/awesome-lists/devtools/parsers-and-language-support/language-variant-support.md) — Chooses an alternative parser variant for a language, such as JSX or TypeScript for JavaScript. ([source](https://docs.grit.io/language/target-languages))
- [Bubble-Scoped Pattern Isolation](https://awesome-repositories.com/f/awesome-lists/devtools/pattern-matching/bubble-scoped-pattern-isolation.md) — Creates new scopes inside patterns so metavariables rebind independently in each match location. ([source](https://docs.grit.io/language/bubble))

### Data & Databases

- [Declarative Code Query Languages](https://awesome-repositories.com/f/data-databases/data-access-querying/api-query-languages/code-analysis-query-languages/declarative-code-query-languages.md) — Identifies and transforms code patterns using declarative rules with metavariables and conditions.
- [Structural Code Searchers](https://awesome-repositories.com/f/data-databases/search-indexing-technologies/search-indexing/search-information-retrieval/code-context-search/structural-code-searchers.md) — Ships a structural code searcher that matches code by AST structure, ignoring formatting differences. ([source](https://docs.grit.io/tutorials/gritql))
- [Language-Specific Parsing Selection](https://awesome-repositories.com/f/data-databases/data-access-querying/api-query-languages/code-analysis-query-languages/language-specific-parsing-selection.md) — Selects a programming language to parse source code with its corresponding abstract syntax tree. ([source](https://docs.grit.io/language/target-languages))
- [Metavariable Subpattern Filters](https://awesome-repositories.com/f/data-databases/query-condition-builders/pattern-matching-filters/metavariable-subpattern-filters.md) — Restricts pattern matching to code nodes where a metavariable matches a specified subpattern for precise targeting. ([source](https://docs.grit.io/language/conditions))
- [Example-Based Code Queries](https://awesome-repositories.com/f/data-databases/semantic-search/code-search/example-based-code-queries.md) — Allows searching source code by providing an example code snippet as the query pattern. ([source](https://docs.grit.io/))

### Programming Languages & Runtimes

- [AST Condition Filters](https://awesome-repositories.com/f/programming-languages-runtimes/language-features-paradigms/language-features/control-flow/pattern-matching/match-guard-filtering/ast-condition-filters.md) — Applies boolean conditions, regular expressions, or AST node checks to restrict which matches are kept or rewritten. ([source](https://docs.grit.io/tutorials/gritql))
- [Query Execution Engines](https://awesome-repositories.com/f/programming-languages-runtimes/rust-based-compilers/query-execution-engines.md) — Processes millions of lines of code efficiently using a compiled Rust runtime with query optimization.
- [Structural Metavariables](https://awesome-repositories.com/f/programming-languages-runtimes/structural-metavariables.md) — Captures and reuses variable parts of matched code through named placeholders for conditions and rewrites.
- [Conditional Transformations](https://awesome-repositories.com/f/programming-languages-runtimes/conditional-transformations.md) — Executes different rewrite rules depending on whether a condition is true or false, enabling branching logic. ([source](https://docs.grit.io/language/conditions))
- [JavaScript Predicate Extensions](https://awesome-repositories.com/f/programming-languages-runtimes/extensible-query-predicates/javascript-predicate-extensions.md) — Ships a JavaScript predicate extension that allows custom matching logic beyond the declarative query syntax.
- [Metavariable Assignments](https://awesome-repositories.com/f/programming-languages-runtimes/structural-metavariables/metavariable-assignments.md) — Binds values to metavariables within condition blocks for reuse in subsequent rewrite rules. ([source](https://docs.grit.io/language/conditions))
- [Contextual Match Filters](https://awesome-repositories.com/f/programming-languages-runtimes/structural-pattern-matching/contextual-match-filters.md) — Restricts a pattern's matches to nodes that satisfy additional structural conditions like parent or sibling relationships. ([source](https://cdn.jsdelivr.net/gh/biomejs/gritql@main/README.md))
- [Contextual Match Restrictions](https://awesome-repositories.com/f/programming-languages-runtimes/structural-pattern-matching/contextual-match-restrictions.md) — Restricts a pattern to only match when it appears inside a specific enclosing code structure. ([source](https://docs.grit.io/tutorials/gritql))
- [Metavariable Scoping](https://awesome-repositories.com/f/programming-languages-runtimes/variable-scope-controls/metavariable-scoping.md) — Binds a metavariable once per file so all occurrences must match the same value for single-edit transformations. ([source](https://docs.grit.io/language/bubble))
- [File-Scoped Metavariables](https://awesome-repositories.com/f/programming-languages-runtimes/variable-scope-controls/metavariable-scoping/file-scoped-metavariables.md) — Uses prefixed metavariables to share state across all matches in a file for accumulating results. ([source](https://docs.grit.io/language/bubble))

### Content Management & Publishing

- [Pattern Definition Files](https://awesome-repositories.com/f/content-management-publishing/authoring-editorial-interfaces/content-authoring-editing/document-authoring-tools/markdown-authoring-environments/pattern-definition-files.md) — Stores patterns in Markdown files using the file name, first heading, first paragraph, and first code block for metadata. ([source](https://docs.grit.io/guides/authoring))

### DevOps & Infrastructure

- [Pattern Directory Loading](https://awesome-repositories.com/f/devops-infrastructure/configuration-management/file-based-configuration/configuration-file-loading/sequential-directory-loading/pattern-directory-loading.md) — Automatically discovers and loads all patterns defined in files placed inside a designated folder. ([source](https://docs.grit.io/guides/patterns))

### Scientific & Mathematical Computing

- [Reusable Predicate Definitions](https://awesome-repositories.com/f/scientific-mathematical-computing/numerical-mathematical-foundations/algorithms-and-complexity/algorithms/graph-processing/shortest-path-algorithms/a-star-search/reusable-predicate-definitions.md) — Creates named predicates that encapsulate conditions for reuse inside a pattern's where clause. ([source](https://docs.grit.io/guides/patterns))

### System Administration & Monitoring

- [Pattern Severity Configurations](https://awesome-repositories.com/f/system-administration-monitoring/audit-log-filters/severity-level-filtering/log-severity-categorization/custom-severity-levels/severity-level-styling/pattern-severity-configurations.md) — Sets a diagnostic level for a pattern to control how it is reported during checks. ([source](https://docs.grit.io/guides/config))

### Testing & Quality Assurance

- [Baseline-Comparison Regression Detections](https://awesome-repositories.com/f/testing-quality-assurance/regression-testing-suites/expectation-based-regression-detection/baseline-comparison-regression-detections.md) — Compares current violations against the last commit on the default branch to detect regressions while tolerating pre-existing issues. ([source](https://docs.grit.io/guides/ci))
- [Inline Pattern Test Cases](https://awesome-repositories.com/f/testing-quality-assurance/software-testing/testing-frameworks/test-frameworks/assertions-and-validation/test-case-definitions/bug-validation-tests/inline-test-case-reproducers/inline-pattern-test-cases.md) — Embeds test cases as subheadings with code blocks for pattern validation. ([source](https://docs.grit.io/guides/authoring))

### User Interface & Experience

- [Pattern Match Combinators](https://awesome-repositories.com/f/user-interface-experience/search-filtering-logic/combinator-logic/pattern-match-combinators.md) — Combines multiple conditions with AND logic so a pattern matches only when all conditions are true. ([source](https://docs.grit.io/language/conditions))

### Web Development

- [Executable Pattern Bundles](https://awesome-repositories.com/f/web-development/single-page-applications/single-file-distributions/documentation-bundles/executable-pattern-bundles.md) — Combines queries, documentation, and test cases into a single Markdown file for reusable pattern distribution. ([source](https://docs.grit.io/guides/testing))