ast-grep-outline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use ast-grep outline

使用ast-grep outline

ast-grep outline

prints a compact structural map of source code with line numbers: top-level items (imports, functions, classes, structs, interfaces, modules, enums) and their direct members (fields, methods, constructors, enum variants). It is a local, syntax-only view — cheap enough to run before any full file read.

Read code in stages: find candidate files with search or file names, outline them, then open only the source range the outline points to. Defaults adapt to input: a file shows its local structure with member digests; a directory shows only its exported surface as grouped names.

ast-grep outline

会打印带行号的紧凑源代码结构概览：包含顶层条目（导入、函数、类、结构体、接口、模块、枚举）及其直接成员（字段、方法、构造函数、枚举变体）。这是一个本地的、仅基于语法的视图——足够轻量，适合在阅读完整文件前运行。

分阶段阅读代码：通过搜索或文件名找到候选文件，生成其结构概览，然后仅打开概览指向的源代码范围。默认行为会适配输入：针对文件时，会显示其本地结构及成员摘要；针对目录时，仅显示按名称分组的导出内容。

When To Use It

适用场景

Understand a file before editing. Get a table of contents, dependencies, and public entry points before reading implementation details:

shell

ast-grep outline <file>
ast-grep outline <file> --items imports
ast-grep outline <file> --items exports

Map an unfamiliar directory. Scan the public surface of a subtree, then narrow by symbol type when you know what you are looking for:

shell

ast-grep outline <dir> --items exports
ast-grep outline <dir> --type struct,enum,function

Zoom into a known symbol. After search finds a likely name, list its members with line numbers instead of reading the whole body:

shell

ast-grep outline <file> --match <symbol> --type class --view expanded

Trace dependency direction. Find which files import a package or module to decide where a change belongs:

shell

ast-grep outline <dir> --items imports --view signatures

Review changed files after editing. Git tells you what changed; outline summarizes the resulting structure and public surface:

shell

ast-grep outline $(git diff --name-only HEAD) --items exports

编辑前理解文件内容：在阅读实现细节前，先获取目录、依赖项和公共入口点：

shell

ast-grep outline <file>
ast-grep outline <file> --items imports
ast-grep outline <file> --items exports

梳理陌生目录结构：扫描子树的公共接口，当明确目标后，按符号类型缩小范围：

shell

ast-grep outline <dir> --items exports
ast-grep outline <dir> --type struct,enum,function

聚焦已知符号：搜索找到目标名称后，列出其成员及对应行号，无需阅读整个代码体：

shell

ast-grep outline <file> --match <symbol> --type class --view expanded

追踪依赖方向：找出哪些文件导入了某个包或模块，以确定修改位置：

shell

ast-grep outline <dir> --items imports --view signatures

编辑后审查变更文件：Git会告诉你哪些内容发生了变更；outline则会总结变更后的结构和公共接口：

shell

ast-grep outline $(git diff --name-only HEAD) --items exports

Argument Guide

参数指南

```
--items <KIND>
```
selects top-level items:
```
structure
```
for local declarations (file default),
```
exports
```
for public API (directory default),
```
imports
```
for dependencies,
```
all
```
when import/export edges matter together.
```
--view <VIEW>
```
controls detail, from least to most:
```
names
```
for directory scans,
```
signatures
```
for one line per item,
```
digest
```
for signatures plus member names,
```
expanded
```
for one line per member with its line number.
```
--match <REGEX>
```
filters top-level items by name or signature. Rust regex, case-sensitive; it never matches members.
```
--type <TYPE[,TYPE...]>
```
keeps only some top-level symbol types, such as
```
--type class,function
```
. Member types like
```
method,field
```
never match top-level items.
```
--pub-members
```
hides private members when the view prints members.
```
--json=stream
```
emits one JSON object per file with precise ranges. Use it only to pipe or post-process entries; prefer text for navigation.

```
--items <KIND>
```
用于选择顶层条目：
```
structure
```
表示本地声明（文件默认值），
```
exports
```
表示公共API（目录默认值），
```
imports
```
表示依赖项，
```
all
```
用于同时关注导入/导出关联。
```
--view <VIEW>
```
控制显示细节程度，从少到多依次为：
```
names
```
用于目录扫描，
```
signatures
```
每个条目一行，
```
digest
```
包含签名及成员名称，
```
expanded
```
每个成员一行并附带行号。
```
--match <REGEX>
```
按名称或签名过滤顶层条目。使用Rust正则表达式，区分大小写；该参数不会匹配成员。
```
--type <TYPE[,TYPE...]>
```
仅保留特定类型的顶层符号，例如
```
--type class,function
```
。成员类型如
```
method,field
```
不会匹配顶层条目。
```
--pub-members
```
在显示成员时隐藏私有成员。
```
--json=stream
```
为每个文件输出一个包含精确范围的JSON对象。仅用于管道传输或后处理条目；导航时优先使用文本格式。

Limits

局限性

outline

shows local syntax structure. It does not resolve references, infer types, follow re-export chains, or build a call graph. Use

ast-grep run

rg

, or compiler-backed tools for those questions, then outline the candidate files they surface.

undefined

outline

仅显示本地语法结构。它不解析引用、推断类型、追踪重导出链或构建调用图。对于这些需求，请使用

ast-grep run

、

rg

或编译器相关工具，然后对它们找到的候选文件生成结构概览。