# ast-grep

> CLI for structural code search, lint, and rewriting that matches tree-sitter AST nodes using patterns written as ordinary code. Written in Rust.

Stars: 16.4k · Language: Rust · License: MIT · Categories: Search

- Repository: https://github.com/ast-grep/ast-grep
- Website: https://ast-grep.github.io/
- Page: https://www.trmn.sh/tools/ast-grep

## Install

- Homebrew: `brew install ast-grep`
- npm: `npm install --global @ast-grep/cli`
- pip: `pip install ast-grep-cli`

## Overview

ast-grep (command: `sg` or `ast-grep`) is a command-line tool for structural code search, linting, and rewriting. It works like grep, but matches abstract syntax tree nodes produced by tree-sitter rather than text. Patterns are written as ordinary code in the target language, and they match all code with the same syntactic structure.

Patterns use `$` followed by upper-case letters, such as `$MATCH`, as a wildcard that matches any single AST node. A search and replace is a single command, for example `ast-grep -p '$A && $A()' -l ts -r '$A?.()'` rewrites a guard-and-call expression in TypeScript into optional call syntax. The `-p` flag gives the pattern, `-l` the language, `-r` the rewrite, and `-i` is used in the README example for interactive rewriting.

Beyond one-off commands, ast-grep supports YAML configuration for writing custom lint rules and code modifications, and the README mentions a jQuery-like API for AST traversal and manipulation. It is written in Rust, parses with tree-sitter, and uses multiple cores. An online playground is available for trying patterns.

Typical users are developers doing large-scale refactors or codemods, library authors who want to help users migrate across breaking changes, tech leads enforcing code conventions, and security researchers writing detection rules.

### Installation

```bash
# via Homebrew
brew install ast-grep
```

```bash
# via npm
npm install --global @ast-grep/cli
```

```bash
# via pip
pip install ast-grep-cli
```

![ast-grep search and replace demo](https://media.trmn.sh/cached/f65b60235a782bfcd30b7341c74c26e3e6b03fb9cbe92eeb5294f3ac8b837b43.png)

## Alternatives

- [rga](https://www.trmn.sh/tools/rga.md): Line-oriented search tool that extends ripgrep to search inside PDFs, archives, documents, and multimedia files (Rust, 9.9k stars)
- [skim](https://www.trmn.sh/tools/skim.md): Fuzzy finder written in Rust with interactive search capabilities and shell integration (Rust, 7.0k stars)
- [television](https://www.trmn.sh/tools/television.md): Fuzzy finder for the terminal that searches files, text, git repositories, and custom data sources in real-time (Rust, 6.4k stars)
- [fd](https://www.trmn.sh/tools/fd.md): Fast filesystem search tool that replaces find with regex patterns and smart defaults (Rust, 44.9k stars)
- [ripgrep](https://www.trmn.sh/tools/ripgrep.md): Fast line-oriented regex search tool that recursively searches directories with automatic gitignore and binary file filtering (Rust, 69.5k stars)

---

Canonical: https://www.trmn.sh/tools/ast-grep