---
schema_version: 1
route: /t/ast-grep.md
tool: "ast-grep"
---

# sincecutoff.com /t/ast-grep — ast-grep

- name: ast-grep
- kind: cli
- children: none
- homepage: <https://github.com/ast-grep/ast-grep>

Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows.
Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json).
To stay current, read the changes feed: [`/v1/changes.md?tool=ast-grep`](https://sincecutoff.com/v1/changes.md?tool=ast-grep) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt).

### ast-grep adds a min-severity CLI option (2026-08-31)
- slug: ast-grep-adds-a-min-severity-cli-option-e5e4abb20771
- score: 0.92

How to use it:

When running repository checks with `ast-grep scan`, use `--min-severity <LEVEL>` to run only rules whose final severity is at least the threshold.

Examples:

```
ast-grep scan --min-severity warning
```

```
ast-grep scan --error=<rule-id> --min-severity error
```

- why_it_matters: Set a minimum severity when running ast-grep checks in a repository.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.45.3>, <https://ast-grep.github.io/guide/project/severity>, <https://ast-grep.github.io/reference/cli/scan>
- gotchas: "Version: 0.45.3"; "--min-severity <LEVEL>: Minimum final rule severity to run; accepted values: `hint`, `info`, `warning`, `error`, `off` (case-insensitive). Default `off` disables filtering."; "--error[=<RULE_ID>...]: Set the named rule's severity to error; repeat for multiple rules. `=` is required when specifying a rule ID. Severity overrides apply before the threshold."

### ast-grep bindings add named-child access (2026-08-23)
- slug: ast-grep-bindings-add-named-child-access-7bd13bac6b0c
- score: 0.90

How to use it:

When traversing a parsed source tree, call `namedChildren()` in the WebAssembly or napi binding, or `named_children()` in PyO3, to get named AST nodes only.

Examples:

```
const nodes = root.namedChildren()
```

```
named = node.named_children()
```

- why_it_matters: Traverse AST nodes through ast-grep's WebAssembly, napi, or PyO3 binding while working with a source tree.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.45.2>, <https://ast-grep.github.io/guide/api-usage/wasm-api>, <https://ast-grep.github.io/guide/api-usage/py-api>
- gotchas: "Version: 0.45.2"; "namedChildren() (required): Returns an array of named AST child nodes; takes no parameters."; "named_children() (required): Returns a list of named AST child nodes; takes no parameters."; "Prerequisite: WebAssembly: install `@ast-grep/wasm` and its `web-tree-sitter` peer dependency; initialize the runtime and register a parser for the language before parsing."; "Prerequisite: PyO3: install the Python library with `pip install ast-grep-py`."

### ast-grep adds outline rules for more builtin languages (2026-07-04)
- slug: ast-grep-adds-outline-rules-for-more-builtin-languages-f2b0bc355403
- score: 0.92

How to use it:

When inspecting code in a builtin language with outline rules, run `ast-grep outline <path>` to view its structure. The 0.44.1 release added outline rules for C, C++, C#, Ruby, and PHP.

Examples:

```
ast-grep outline <path>
```

- why_it_matters: Inspect the structure of code written in a builtin language supported by ast-grep.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.44.1>, <https://ast-grep.github.io/reference/cli/outline>
- gotchas: "Version: 0.44.1"; "<path>: Path or paths to search; defaults to the current directory when omitted."

### ast-grep adds outline extraction and an outline CLI (2026-06-22)
- slug: ast-grep-adds-outline-extraction-and-an-outline-cli-82ce3014c994
- score: 0.97

How to use it:

To inspect a file or directory’s structure, run `ast-grep outline` on the target path; bundled outline rules are used automatically. Choose `--items` and `--view` to narrow the output, and use `--outline-rules` only to add extractor definitions.

Examples:

```
ast-grep outline <file>
```

```
ast-grep outline <directory> --items exports
```

```
ast-grep outline <path> --outline-rules <rules.yml>
```

- why_it_matters: Inspect source files in a repository using ast-grep's outline extraction.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.44.0>, <https://ast-grep.github.io/guide/outline-code>, <https://ast-grep.github.io/reference/cli/outline>
- gotchas: "Version: 0.44.0"; "<file> / <directory> (PATHS): Path or paths to search; defaults to the current directory."; "--items <ITEMS>: Select top-level entries: `auto`, `structure`, `exports`, `imports`, or `all`. `auto` adapts to input; directory input defaults to exports."; "--view <VIEW>: Select output detail: `auto`, `names`, `signatures`, `digest`, or `expanded`. These values are alternatives; `auto` uses names for directories and digest for files or stdin."; "--outline-rules <FILE>: Load additional extractor definitions from a stream of YAML documents; rules supplement bundled rules and configured custom-language rules."; "--no-default-outline-rules: Disable bundled extractor definitions; combine with `--outline-rules` to replace the built-in catalog."; "Prerequisite: The outline command was introduced in ast-grep 0.44.0 as an alpha preview."

### ast-grep sg test adds --follow (2026-05-25)
- slug: ast-grep-sg-test-adds-follow-2a96d9ab26e6
- score: 0.93

How to use it:

When testing ast-grep rules and you need to follow target paths or files, pass `--follow` to `sg test`.

- why_it_matters: Test code with ast-grep while following the target paths or files.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.43.0>
- gotchas: "Version: 0.43.0"; "--follow: The 0.43.0 release note adds this argument to `sg test`; official CLI reference documentation does not document it for `test`."

### ast-grep adds the no-suppress-all built-in rule (2026-04-04)
- slug: ast-grep-adds-the-no-suppress-all-built-in-rule-7d0c3bb9853b
- score: 0.94

How to use it:

When checking for diagnostics hidden by suppress-all comments, run ast-grep’s built-in `no-suppress-all` rule on the repository. It reports `ast-grep-ignore` comments that omit a rule ID.

Examples:

```
ast-grep scan --warning=no-suppress-all
```

```
ast-grep scan --error=no-suppress-all
```

- why_it_matters: Check code for suppressed diagnostics using ast-grep's built-in rules.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.42.1>, <https://ast-grep.github.io/reference/cli/scan>, <https://ast-grep.github.io/guide/project/severity>
- gotchas: "Version: 0.42.1"; "--warning=no-suppress-all: Sets the `no-suppress-all` rule severity to warning; the rule is otherwise not enabled by default."; "--error=no-suppress-all: Sets the `no-suppress-all` rule severity to error; an error rule match makes the scan exit non-zero."; "[PATHS]...: Paths to search; defaults to the current directory (`.`)."

### ast-grep adds a parameterized util (2026-03-16)
- slug: ast-grep-adds-a-parameterized-util-7d4f836e173a
- score: 0.94

How to use it:

When a rule needs a reusable global utility customized for different contexts, define parameters on the utility and pass a rule object for every parameter through the caller’s `matches` rule.

Examples:

```
# utils/audit-log-call.yml
id: audit-log-call
arguments: [logger-rule]
language: TypeScript
rule:
  pattern: $OBJ.$METHOD($$$ARGS)
  all:
    - has:
        kind: member_expression
        has:
          field: object
          matches: logger-rule
    - has:
        field: arguments
        has:
          kind: string

# rules/audit-logging.yml
id: no-console-string
language: TypeScript
rule:
  matches:
    audit-log-call:
      logger-rule: { regex: ^console$ }
```

- why_it_matters: Use ast-grep's parameterized util while maintaining or changing repository code.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.42.0>, <https://ast-grep.github.io/blog/new-ver-42>
- gotchas: "Version: 0.42.0"; "arguments: Utility declaration list of parameter names. Every declared parameter must be supplied at the call site; there are no optional parameters."; "<parameter name> (for example, logger-rule) (required): At the call site, provide a full ast-grep rule object as the value; arguments are rules, not strings."; "matches (required): In the utility body, a bare parameter name in `matches` refers to the bound rule. At the call site, `matches` names the parameterized global utility and maps each argument name to its rule object."; "Prerequisite: Use ast-grep 0.42 parameterized utilities; the release documentation labels this feature experimental."; "Prerequisite: Parameters can be declared only by global utility rules in separate YAML files under the `utils/` directory; the utility has `id`, `language`, and `rule`."; "Prerequisite: All declared arguments must be supplied. The documentation does not state that parameters are mutually exclusive."

### ast-grep supports the :not selector (2026-03-16)
- slug: ast-grep-supports-the-not-selector-b7547bc19570
- score: 0.92

How to use it:

When a query needs to exclude nodes matching a selector, use ast-grep’s `:not` selector in `--kind` to search the repository. The selector negates its inner selector.

Examples:

```
ast-grep run --kind 'expression_statement:not(:has(> call_expression))' <path>
```

```
ast-grep run --kind 'identifier:not(number)' <path>
```

- why_it_matters: Query repository code while excluding nodes that match a selector condition.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.42.0>, <https://ast-grep.github.io/blog/new-ver-42>, <https://ast-grep.github.io/reference/rule/esquery>, <https://github.com/ast-grep/ast-grep.github.io/blob/main/website/reference/cli.md>
- gotchas: "Version: 0.42.0"; "--kind <KIND> (required): AST kind or ESQuery-style selector to match. Use `:not(selector)` to negate the inner selector."; "[PATHS]...: Paths to search; defaults to `.`. Multiple paths may be separated by spaces."

### ast-grep files/ignores support a case insensitive option (2026-01-10)
- slug: ast-grep-files-ignores-support-a-case-insensitive-option-a6fcb788cbeb
- score: 0.93

How to use it:

When a rule should include or exclude paths regardless of case, configure its `files` or `ignores` list with a glob object and set `caseInsensitive: true`.

Examples:

```
files:
  - glob: '<glob>'
    caseInsensitive: true
```

```
ignores:
  - glob: '<glob>'
    caseInsensitive: true
```

- why_it_matters: Configure case-insensitive matching for files or ignores in an ast-grep workflow.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.40.5>, <https://ast-grep.github.io/reference/yaml>
- gotchas: "Version: 0.40.5"; "files: Array of glob patterns limiting which files a rule applies to; each item can be a string or an object with `glob` and `caseInsensitive`."; "ignores: Array of glob patterns excluding files from a rule; each item can be a string or an object with `glob` and `caseInsensitive`."; "glob (required): Pattern string in a glob object."; "caseInsensitive: Whether glob matching is case insensitive; defaults to `false`."

### ast-grep supports --files-with-matches (2026-01-05)
- slug: ast-grep-supports-files-with-matches-87f0c104f861
- score: 0.95

How to use it:

When you need matching file names for a structural search, run ast-grep with `--files-with-matches` and provide a pattern, language, and repository path.

Examples:

```
ast-grep run --pattern '<AST pattern>' --lang <language> --files-with-matches <repository-path>
```

- why_it_matters: List the files in a repository that match an ast-grep search.
- sources: <https://github.com/ast-grep/ast-grep/releases/tag/0.40.4>, <https://ast-grep.github.io/reference/cli/run>
- gotchas: "Version: 0.40.4"; "--pattern <PATTERN> (required): AST pattern to match."; "--lang <LANG>: Language of the pattern."; "[PATHS]...: Paths to search; multiple paths are space-separated and default to `.`."; "--files-with-matches: Lists matching files, like ripgrep."