grep-ast

library0.9.0pypypiunverified

grep-ast is a command-line tool designed to search through the Abstract Syntax Tree (AST) of source code files. Unlike traditional `grep` which operates on text, `grep-ast` provides a context-aware output, showing how matching lines fit into the broader code structure (functions, classes, etc.). It leverages `tree-sitter` and `tree-sitter-languages` for parsing various programming languages. The current version is 0.9.0, released in May 2025.

devops testing

pip install grep-ast

github ↗package ↗

INSTALL

IMPORT

SIG · GREP-AST

grep-ast

devopspythonv0.9.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

To quickly search for a pattern in a specific file or recursively in the current directory, use the `grep-ast` command followed by your pattern and optional filenames or paths. By default, it respects .gitignore. You can also use `gast` as an alias.

grep-ast "function_name" my_module.py grep-ast "class MyClass" .

grep-ast --version

Debug

Known issues

gotchaThis `grep-ast` tool is distinct from the `ast-grep` (Rust-based) project, despite similar names and AST-related functionality. `grep-ast` focuses on text-based regex search with AST-aware output, while `ast-grep` (and its Python binding `ast-grep-py`) uses AST patterns for search and rewrite.

fix

Ensure you are using the correct tool for your desired functionality; if you need AST-pattern matching or rewriting, consider `ast-grep` or `ast-grep-py`.

affects: All

gotchaThe search patterns provided to `grep-ast` are regular expressions applied to the *text* of the code, not directly to AST nodes. The AST is used to provide context for the matched text lines, not for pattern matching itself.

fix

Formulate your patterns as standard regular expressions. If you require matching against the structural properties of the AST directly, tools like `ast-grep` are designed for that.

affects: All

gotchaBy default, `grep-ast` recursively searches the current directory and respects `.gitignore`. This might lead to unexpected results if you intend to search files outside the Git repository's scope or want to override `.gitignore` rules.

fix

Explicitly specify target files or directories to limit the search scope. Use the `--no-gitignore` option if you need to bypass `.gitignore` filtering (check the latest CLI options for availability).

affects: All

Errors

Common errors & fixes

grep-ast: command not found

The `grep-ast` executable is not in the system's PATH, or the package was not installed in a way that makes the script directly executable.

fix

Ensure `grep-ast` is installed correctly and its installation directory (often within the Python environment's `bin` or `Scripts` folder) is in your system's PATH. Alternatively, run it directly using `python -m grep_ast [pattern] [filenames...]`.

ModuleNotFoundError: No module named 'grep_ast'

The `grep-ast` Python package is not installed in the current Python environment or is corrupted.

fix

Install the package using pip: `pip install grep-ast`. If you intend to install from the source, use `python -m pip install git+https://github.com/paul-gauthier/grep-ast.git`. Ensure you are working in the correct Python environment.

Pattern not matching expected code

The provided pattern does not accurately represent the Abstract Syntax Tree (AST) structure that `grep-ast` expects for the target code, as users often think textually rather than structurally.

fix

Simplify your pattern and use the `--verbose` flag (or a similar debug option if available, like `ast-grep`'s `--debug-query=ast`) to inspect the actual AST structure of the code you're trying to match, then adjust your pattern to reflect the AST nodes and their relationships.

Language not supported

`grep-ast` relies on `tree-sitter` and `tree-sitter-languages` for parsing, and the language of the input file might not be supported, or the necessary parser might not be installed or configured.

fix

Check the list of supported languages by consulting the `grep-ast` documentation or using `grep-ast --languages` if that option is available. Ensure the file extension is correctly recognized or explicitly specify the language using a `--lang` argument if the tool provides one.

Upgrade

Version history

0.9.0latest on PyPI · released May 8, 2025

Audit

Dependencies

tree-sitterrequiredCore parsing engine for AST generation, though not directly declared as a Python dependency on PyPI, it's fundamental to its operation.

tree-sitter-languagesrequiredProvides language-specific parsers used by tree-sitter for diverse language support.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/paul-gauthier/grep-ast ↗

packagehttps://pypi.org/project/grep-ast/ ↗