ast-grep outline
Explore code structure for symbols, imports, exports, and members.
Use outline to inspect file structure, imports, exports, and direct members before opening full source files.
For the item/member concepts behind this output, see How Outline Entries Work.
Usage
ast-grep outline [OPTIONS] [PATHS]...Arguments
[PATHS]...
The paths to search. You can provide multiple paths separated by spaces.
[default: .]
When no path is provided and --stdin is not used, outline searches the current directory.
Outline Options
--items <ITEMS>
Select top-level items before --match and --type filtering.
[default: auto]
Possible values:
auto: use the file, directory, or stdin default.structure: include top-level structure whereisImportis false.exports: include top-level items whereisExportedis true.imports: include top-level items whereisImportis true.all: include all top-level items, including imports and explicit export edges.
--view <VIEW>
Control text presentation.
[default: auto]
Possible values:
auto: usenamesfor directory input anddigestfor file or stdin input.names: group top-level item names by symbol type.signatures: show one source/signature line per top-level item.digest: show signatures plus compact direct member name digests.expanded: show one source/signature line per top-level item and direct member.
--match <REGEX>
Filter top-level items with a Rust regular expression.
The regex is applied to useful top-level item fields: name, signature, and first source line. It is case-sensitive by default. Invalid regexes are CLI errors.
--match does not filter members directly.
--type <TYPE[,TYPE...]>
Filter top-level items by symbol type.
Use lower camel case symbol type names such as class, function, struct, enumMember, and typeParameter. Multiple values are comma-separated and work as an OR filter.
Examples:
ast-grep outline crates --type struct,enum,interface
ast-grep outline src/parser.ts --match Parser --type class--type filters top-level items only. It does not select class methods or fields unless those symbols are extracted as top-level items in the source.
--pub-members
Show only public or externally usable members in digest and expanded views.
If an extractor omits member publicness, outline treats the member as public.
--outline-rules <FILE>
Load additional outline extractor definitions.
Each file is a stream of YAML documents. These rules are loaded in addition to bundled extractor definitions, top-level project outlineRules, and enabled custom language outline rules in sgconfig.yml. Command-line files load after configured files.
See outline extraction rule reference.
--no-default-outline-rules
Disable bundled extractor definitions.
Project outlineRules, enabled custom language rules, and command-line --outline-rules files remain loaded.
Input Options
-l, --lang <LANG>
Specify the input language.
For path input, ast-grep parses only files of this language. For stdin, this flag is required because ast-grep cannot infer a language from standard input.
-c, --config <CONFIG_FILE>
Path to ast-grep root config.
[default: sgconfig.yml]
outline uses project config for top-level outlineRules, custom language registration, and customLanguages.<name>.outlineRules.
--custom-languages <CUSTOM_LANGUAGES>
Control loading of native parsers and their configured outlineRules. See global options and the custom language guide.
--stdin
Read source from standard input.
Use this with --lang:
cat src/parser.ts | ast-grep outline --stdin --lang ts--globs <GLOBS>
Include or exclude file paths.
Globbing rules match .gitignore globs. Prefix a glob with ! to exclude it. Multiple --globs flags may be used.
--follow
Follow symbolic links while traversing directories.
--no-ignore <FILE_TYPE>
Do not respect hidden file system or ignore files.
When omitted, this option inherits values from the noIgnore field of sgconfig.yml. Supplying one or more values overrides the configured list.
See the noIgnore reference for possible values.
-j, --threads <NUM>
Set the approximate number of threads to use.
The default value 0 lets ast-grep choose a thread count using heuristics.
[default: 0]
Output Options
--json[=<STYLE>]
Output selected outline entries as JSON.
Possible values:
pretty: pretty-printed JSON. This is the default when--jsonis passed without a value.compact: compact single-line JSON.stream: newline-delimited file objects.
The JSON shape is grouped by file. --json=stream emits the same file object shape once per line.
--color <WHEN>
Control ANSI color in text output.
[default: auto]
Possible values:
autoalwaysansinever
Text Output
Text output depends on --view:
src/parser.ts
class: Parser
function: parseRule, parsePatternsrc/parser.ts
12: export function parseRule(...)
40: export class Parsersrc/parser.ts
12: export function parseRule(...)
40: export class Parser
methods: parse, recoversrc/parser.ts
12: export function parseRule(...)
40: export class Parser
44: parse(...)
73: recover(...)For direct file and stdin input, an empty result prints an explicit file block:
src/empty.ts
nothing foundDirectory walks suppress files with no selected items. If a directory or mixed-input command selects nothing overall, outline prints one command-level nothing found message.
JSON Output
JSON output contains file objects. --json and --json=compact emit an array of file objects. --json=stream emits one file object per line.
One file object looks like this:
{
"path": "src/parser.ts",
"language": "TypeScript",
"items": [
{
"name": "Parser",
"symbolType": "class",
"role": "item",
"isImport": false,
"isExported": true,
"range": {
"byteOffset": { "start": 1200, "end": 2500 },
"start": { "line": 39, "column": 0 },
"end": { "line": 97, "column": 1 }
},
"signature": "export class Parser",
"astKind": "class_declaration",
"members": [
{
"name": "parse",
"symbolType": "method",
"role": "member",
"isPublic": true,
"range": {
"byteOffset": { "start": 1300, "end": 1900 },
"start": { "line": 43, "column": 2 },
"end": { "line": 71, "column": 3 }
},
"signature": "parse(...)",
"astKind": "method_definition"
}
]
}
]
}The output shape is:
/** `--json` and `--json=compact` emit this array shape. */
type OutlineJsonOutput = OutlineFile[]
interface OutlineFile {
path: string
language: string
items: OutlineItem[]
}
/** Shared fields for top-level items and direct members. */
interface OutlineEntry {
/** Lower camel case name compatible with LSP SymbolKind. */
symbolType: string
name: string
/** Zero-based line/column positions plus byte offsets. */
range: OutlineRange
signature: string
astKind: string
}
interface OutlineItem extends OutlineEntry {
role: 'item'
isImport: boolean
isExported: boolean
/** Direct syntactic children selected by the current view. */
members?: OutlineMember[]
}
interface OutlineMember extends OutlineEntry {
role: 'member'
isPublic: boolean
}
interface OutlineRange {
byteOffset: {
start: number
end: number
}
start: OutlinePosition
end: OutlinePosition
}
interface OutlinePosition {
line: number
column: number
}For --json=stream, parse each line as OutlineFile instead of parsing the whole output as OutlineJsonOutput.
Default Behavior
outline chooses defaults based on the input:
| Input | Equivalent default |
|---|---|
| Stdin | --items structure --view digest |
| Explicit files only | --items structure --view digest |
| Any directory input | --items exports --view names |
When files and directories are mixed, the directory default is used for the whole command.
Exit Codes
The program exits with status code:
0: command completed, including an empty outline.2: fatal read, parse, or configuration error.
Invalid CLI arguments are reported by clap.