ast-grep

Search for a pattern in the current directory

$ ast-grep --pattern '[console.log($ARG)]'

$ ast-grep --pattern '[async function $NAME() {}]' --lang typescript

$ ast-grep --pattern '[$OLD].forEach($FN)' --rewrite '[$OLD].map($FN)'

$ ast-grep --pattern '[$A] == [$B]' --rewrite '[$A] === [$B]' --interactive

$ ast-grep --pattern '[var $X = $Y]' --json

$ ast-grep scan

$ ast-grep --pattern '[TODO]' --context 3

ast-grep [command] [options]
sg [command] [options]

ast-grep (also invoked as sg) is a structural code search and rewriting tool. Unlike text-based grep, it parses code into an Abstract Syntax Tree (AST) and matches patterns at the syntactic level, ensuring matches respect code structure.
Patterns use a code-like syntax where $METAVARIABLES match any expression. For example, console.log($MSG) matches any console.log call regardless of its argument. This enables precise refactoring that text-based tools cannot achieve.
The tool supports multiple languages through tree-sitter parsers, including JavaScript, TypeScript, Python, Rust, Go, C, C++, Java, and more. The scan command applies rules from YAML configuration files, enabling project-wide linting and enforcement of code patterns.
Configuration files (sgconfig.yml) define rule directories and project settings. Individual rules specify patterns, rewrites, severity levels, and file filters.

run

Run a one-time search or rewrite (default command)

Scan and rewrite code using configuration rules

Test ast-grep rules

Create new ast-grep project, rules, or tests

Start language server for IDE integration

AST pattern to search for; use $VAR for metavariables

Replacement pattern for matches

Target language (javascript, typescript, python, rust, go, etc.)

Interactive mode for confirming rewrites

Output in JSON format (pretty, stream, compact)

Show num lines after each match

Show num lines before each match

Show num lines around each match

Read code from standard input

Number of threads (0 for auto-detection)

Path to config file (default: sgconfig.yml)

The sg alias conflicts with the Linux setgroups command; use the full ast-grep command or create a custom alias. Pattern syntax varies slightly by language due to AST differences. Complex patterns may require understanding tree-sitter node types.

ast-grep was created by Herrington Darkholme and released in 2022. Written in Rust for performance, it was designed to bring structural code search to the command line, inspired by tools like Semgrep and Comby. The tool gained popularity for its speed and intuitive pattern syntax for code refactoring tasks.

grep(1), ripgrep(1), sed(1), semgrep(1)