{"id":3506,"library":"grep-ast","title":"grep-ast","description":"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.","status":"active","version":"0.9.0","language":"python","source_language":"en","source_url":"https://github.com/paul-gauthier/grep-ast","tags":["AST","grep","code analysis","cli","tree-sitter","developer tool"],"install":[{"cmd":"pip install grep-ast","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core parsing engine for AST generation, though not directly declared as a Python dependency on PyPI, it's fundamental to its operation.","package":"tree-sitter","optional":false},{"reason":"Provides language-specific parsers used by tree-sitter for diverse language support.","package":"tree-sitter-languages","optional":false}],"imports":[],"quickstart":{"code":"grep-ast \"function_name\" my_module.py\ngrep-ast \"class MyClass\" .","lang":"bash","description":"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."},"warnings":[{"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`.","message":"This `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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All"},{"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).","message":"By 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'0.9.0':74 '2025':78 'abstract':18 'analysi':82 'ast':3,6,21,35,79 'awar':40 'broader':49 'class':53 'cli':83 'code':24,50,81 'command':10 'command-lin':9 'context':39 'context-awar':38 'current':71 'design':13 'develop':87 'etc':54 'file':25 'fit':46 'function':52 'grep':2,5,28,34,80 'grep-ast':1,4,33 'languag':64,69 'leverag':56 'line':11,45 'match':44 'may':77 'oper':30 'output':41 'pars':66 'program':68 'provid':36 'releas':75 'search':15 'show':42 'sitter':59,63,86 'sourc':23 'structur':51 'syntax':19 'text':32 'tool':12,88 'tradit':27 'tree':20,58,62,85 'tree-sitt':57,84 'tree-sitter-languag':61 'unlik':26 'various':67 'version':72","created_at":"2026-04-11T17:32:31.808719+00:00","updated_at":"2026-04-16T15:28:32.036089+00:00","problems":[{"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...]`.","cause":"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.","error":"grep-ast: command not found"},{"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.","cause":"The `grep-ast` Python package is not installed in the current Python environment or is corrupted.","error":"ModuleNotFoundError: No module named 'grep_ast'"},{"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.","cause":"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.","error":"Pattern not matching expected code"},{"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.","cause":"`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.","error":"Language not supported"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"grep-ast","cli_version":"usage: grep-ast [-h] [--encoding ENCODING] [--languages] [-i] [--color]","type":"library","homepage":null,"github":"https://github.com/paul-gauthier/grep-ast","docs":null,"changelog":null,"pypi":"https://pypi.org/project/grep-ast/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-11","next_check":"2026-07-10","install_tag":null}}