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. It is a local code-navigation command, not a search, lint, rewrite, or semantic-analysis command.

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 where isImport is false.
• exports: include top-level items where isExported is true.
• imports: include top-level items where isImport is true.
• all: include all top-level items, including imports and explicit export edges.

--view <VIEW>

Control text presentation.

[default: auto]

Possible values:

• auto: use names for directory input and digest for 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 and any outline rules configured on custom languages in sgconfig.yml.

See outline extraction rule reference.

--no-default-outline-rules

Disable bundled extractor definitions.

Use this with --outline-rules when you want a project-specific extractor catalog to replace the built-in one.

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 custom language registration and for customLanguages.<name>.outlineRules.

--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.

Possible values:

• hidden
• dot
• exclude
• global
• parent
• vcs

-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 --json is 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:

• auto
• always
• ansi
• never

Text Output

Text output depends on --view:

names

src/parser.ts
class: Parser
function: parseRule, parsePattern

signatures

src/parser.ts
12: export function parseRule(...)
40: export class Parser

digest

src/parser.ts
12: export function parseRule(...)
40: export class Parser
    methods: parse, recover

expanded

src/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 found

Directory 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:

{
  "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"
        }
      ]
    }
  ]
}

Important properties:

• path is always present.
• range is always present.
• JSON ranges use zero-based line and column numbers plus byte offsets.
• symbolType uses lower camel case names compatible with LSP SymbolKind.
• role is item or member.
• isImport and isExported are present on top-level items.
• isPublic is present on members.
• Members are nested under their parent item.

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.