Skip to content

xpd run

Search code by syntax, in any language ast-grep parses, and preview or apply a rewrite Use xpd run to find code by its syntax, in any language that ast-grep parses, and to preview or apply a rewrite of each match. It reads the code without running it. A pattern such as $X.iterrows() matches the code it spells out, where $X stands for any one syntax node and $$$ARGS for any number of them. xpd query is another name for the same command.

Terminal window
xpd run [OPTIONS] <--pattern <PATTERN>|--kind <KIND>> [PATHS]...

Also called xpd query.

xpd run --help ends with these lines.

Exit 0 when something matched, 1 when nothing did, 2 if xpd can't run.
Examples:
xpd run -p 'pd.concat($$$FRAMES)' src/
xpd run -k call_expression -l ts web/
xpd run -p '$S.tz_convert("UTC").tz_localize(None)' -r '$S.tz_convert(None)' analysis.py
xpd run -p 'np.matrix($A)' -r 'np.asarray($A)' -U src/
cat job.py | xpd run -p 'print($$$A)' -l python --stdin --json

<PATHS>...

Files or directories (directories respect .gitignore)

Default: ..

-p, --pattern <PATTERN>

The pattern to match, as code with metavariables such as $X and $$$ARGS.

--selector <KIND>

The kind of the part of the pattern that is the actual match.

--strictness <STRICTNESS>

How exactly the pattern must match.

Value Meaning
cst Every node, including punctuation
smart Every node except trivial ones (the default)
ast Named nodes only
relaxed Named nodes, without comments
signature Named nodes without comments, and without comparing their text
template The text of the nodes, whatever their kinds

-k, --kind <KIND>

The syntax kind to match, or an ESQuery-style selector such as call > identifier.

Cannot be combined with --pattern.

-r, --rewrite <FIX>

The code that replaces each match. Metavariables of the pattern are filled in.

-l, --lang <LANG>

The language of the pattern. Without it, each file's extension names its language.

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.

--debug-query[=<DEBUG_QUERY>]

Print the syntax tree of the pattern on stderr.

The value is optional. Give it as --debug-query=<VALUE>.

Values: pattern, ast, cst, sexp.

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

--stdin

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

--globs <GLOBS>

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

Give it more than once to pass several values.

-j, --threads <NUM>

Threads to use. 0 lets ast-grep choose.

Default: 0.

-i, --interactive

Confirm each rewrite, or edit the match in your editor.

-U, --update-all

Apply every rewrite without asking.

--files-with-matches

Print only the paths of files that match.

Cannot be combined with --interactive, --update-all, --json, --format.

--json[=<STYLE>]

Print the matches, and each rewrite as a preview, as JSON (pretty unless a style is given). JSON never writes files, so it conflicts with --update-all.

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

Values: pretty, compact, stream.

--format <FORMAT>

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

Values: text, json.

--color <WHEN>

When to color the text output.

Default: auto.

Values: auto, always, ansi, never.

--heading <WHEN>

When to print the file name above its matches instead of before each one.

Default: auto.

Values: auto, always, never.

-A, --after <NUM>

Lines to show after each match.

Default: 0. Cannot be combined with --context.

-B, --before <NUM>

Lines to show before each match.

Default: 0. Cannot be combined with --context.

-C, --context <NUM>

Lines to show around each match.

Default: 0.

-c, --config <CONFIG_FILE>

The ast-grep project file, whose utility rules and custom languages the pattern can use. Default: the sgconfig.yml in this folder or the nearest one above it.

Give exactly one of --pattern and --kind.

Terminal window
$ xpd run --lang python --pattern '$X.iterrows()' samples/bad.py --format text
samples/bad.py:5:for i, row in df.iterrows():

A rewrite only prints a diff until you pass -U to write every rewrite, or -i to choose each one. xpd does not check a rewrite or mark it safe the way it does a rule fix, so read the diff before you write it.

Terminal window
$ xpd query -p 'pd.merge($$$A)' -r 'df.merge(other, on="k")' samples/bad.py --format text --color never
samples/bad.py
@@ -4,7 +4,7 @@
5 5 │ for i, row in df.iterrows():
6 6 │ df["a"][i] = row["a"] * 2
7 7 │ df.dropna(inplace=True)
8 │-m = pd.merge(df, other, on="k")
8 │+m = df.merge(other, on="k")
9 9 │ out = pd.DataFrame()
10 10│ for f in ["x.csv"]:
11 11│ out = pd.concat([out, pd.read_csv(f)])

--format json prints the matches. Lines and columns in the JSON count from zero, so "line":4 is the line that the text output shows as line 5.

Terminal window
$ xpd run -p '$X.iterrows()' samples/bad.py --format json | jq -c '.[0] | keys, .range'
["charCount","file","language","lines","metaVariables","range","text"]
{"byteOffset":{"start":99,"end":112},"start":{"line":4,"column":14},"end":{"line":4,"column":27}}

--debug-query prints the syntax tree of the pattern on stderr, which shows why a pattern matches less than you expect.

Exit code Meaning
0 Something matched
1 Nothing matched
2 xpd could not run