knoopx/grit

gritql (grit)

Searches and rewrites source code using a declarative query language backed by tree-sitter. Any valid code snippet in backticks is a pattern — no AST vocabulary required. Install: curl -fsSL https://docs.grit.io/install | bash or npm install --location=global @getgrit/cli.

Searching Code

Find matches structurally (whitespace-insensitive):

grit apply '`console.log($_)`' ./src/

Patterns match the AST structure — variations in formatting are handled automatically.

Rewriting Code

Replace patterns in-place:

# Replace console.log with winston
grit apply '`console.log($msg)` => `winston.log($msg)`' ./src/

# Delete matches by rewriting to dot
grit apply '`debugger;' => .' ./src/

Always verify with --dry-run first. Language-specific targeting:

grit apply -l ts '`console.log($_)`' ./src/       # TypeScript only
grit apply -l py 'def $_($$$args) -> $_:' ./src/   # Python

Using the Standard Library

200+ built-in patterns available by name:

grit apply no_console_log               # Remove console.log
grit apply react_to_hooks               # Class components → hooks
grit list                               # List all available patterns

Browse patterns at github.com/biomejs/gritql-stdlib. Import remote patterns in .grit/grit.yaml:

patterns:
  - name: github.com/getgrit/stdlib#no_dead_code
    level: error

Saving Patterns for Reuse

Store patterns in .grit/patterns/ as .md or .grit files, then run by name:

mkdir -p .grit/patterns
# Create .grit/patterns/use_winston.md with the pattern body
grit apply use_winston ./src/
grit check   # Enforce as lint (fails on error/warn level patterns)

Tips

• Use the GritQL Studio to experiment and debug syntax trees
• Patterns must be valid code in backticks — bare metavariables do not work
• Metavariable names: $lowercase_snake_case, anonymous is $_, spread is $...