Skip to content

xpd outline

Map the files of a project: imports, definitions and their members, with line numbers Use xpd outline to map what files import and define before you read them in full. It lists definitions, imports and members with line numbers and signatures, without running any code, in any language that ast-grep parses.

Terminal window
xpd outline [OPTIONS] [PATHS]...

xpd outline --help ends with these lines.

Examples:
xpd outline features.py
xpd outline src/ --view digest
xpd outline . --items imports --format json
xpd outline src/ --type class,function --match '^Frame'
cat job.py | xpd outline --stdin --lang python

<PATHS>...

Files or directories (directories respect .gitignore)

Default: ..

-l, --lang <LANG>

The language to read. With paths, only files of this language are read.

Values: bash, c, cc, c++, cpp, cxx, cs, csharp, css, dart, ex, elixir, go, golang, hs, haskell, hcl, html, java, javascript, js, jsx, json, kotlin, kt, lua, markdown, md, nix, php, py, python, rb, ruby, rs, rust, scala, sol, solidity, swift, tsx, ts, typescript, yaml, yml, zig.

--stdin

Read the code from stdin, in the language of --lang.

--format <FORMAT>

Output format. Default: text on a terminal, json otherwise. JSON is one line.

Values: text, json.

--json[=<STYLE>]

Print JSON (pretty unless a style is given)

The value is optional. Give it as --json=<VALUE>. Cannot be combined with --format.

Values: pretty, compact, stream.

--items <ITEMS>

Which top-level items to list.

Default: auto.

Value Meaning
auto structure for files and stdin, exports when a directory is given
structure What each file defines, without its imports
exports What each file exports: public names in Python
imports What each file imports
all

--type <TYPE>

Keep the items of these symbol types, separated by commas.

Give it more than once to pass several values.

Values: file, module, namespace, package, class, method, property, field, constructor, enum, interface, function, variable, constant, string, number, boolean, array, object, key, null, enumMember, struct, event, operator, typeParameter.

--match <REGEX>

Keep the items whose name or signature matches this regular expression.

--pub-members

List only public members.

--view <VIEW>

How to print the items as text.

Default: auto.

Value Meaning
auto digest for files and stdin, names when a directory is given
names The names of each file, one line per kind of symbol
signatures One line per item, with its line number and signature
digest The signatures, each with the names of its members
expanded The signatures, each with one line per member

--outline-rules <FILE>

More outline rule files, in the schema of ast-grep outline --outline-rules.

Give it more than once to pass several values.

--no-default-outline-rules

Do not use the rules that ship with xpd.

--follow

Follow symbolic links.

--no-ignore <FILE_TYPE>

Ignore files to disregard. Repeat the flag for more than one.

Give it more than once to pass several values.

Value Meaning
hidden Read hidden files and directories
dot Disregard .ignore files
exclude Disregard .git/info/exclude
global Disregard the global git ignore file
parent Disregard ignore files in parent directories
vcs Disregard .gitignore files

--globs <GLOBS>

Include or exclude paths that match a glob, as in .gitignore. ! excludes.

Give it more than once to pass several values.

A file gets its definitions, each with the names of its members.

Terminal window
$ xpd outline samples/graph/steps.py --format text
samples/graph/steps.py
14: LARGE_ORDER = 1000.0
15: PRICE = "unit_price"
18: def totals(orders: pd.DataFrame) -> pd.DataFrame
variable: orders
28: def shares(orders: pd.DataFrame) -> pd.DataFrame
variable: orders
33: def discounts(orders: pd.DataFrame) -> pd.DataFrame
variable: orders
41: def flags(orders: pd.DataFrame) -> pd.DataFrame
variable: orders
51: def features(orders: pd.DataFrame) -> pd.DataFrame
variable: orders

A folder gets a shorter view, with the public names of each file grouped by kind. --type, --match and --view narrow it down.

Terminal window
$ xpd outline samples/graph --type function --match '^(totals|flags)' --view signatures --format text
samples/graph/steps.py
18: def totals(orders: pd.DataFrame) -> pd.DataFrame
41: def flags(orders: pd.DataFrame) -> pd.DataFrame

--globs keeps or drops paths by a glob, and --follow follows symbolic links when it walks a folder.

Exit code Meaning
0 The outline was printed
2 xpd could not run, or it could not read a path