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.
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 --jsonArguments
Section titled “Arguments”<PATHS>
Section titled “<PATHS>”<PATHS>...
Files or directories (directories respect .gitignore)
Default: ..
Options
Section titled “Options”--pattern
Section titled “--pattern”-p, --pattern <PATTERN>
The pattern to match, as code with metavariables such as $X and $$$ARGS.
--selector
Section titled “--selector”--selector <KIND>
The kind of the part of the pattern that is the actual match.
--strictness
Section titled “--strictness”--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 |
--kind
Section titled “--kind”-k, --kind <KIND>
The syntax kind to match, or an ESQuery-style selector such as call > identifier.
Cannot be combined with --pattern.
--rewrite
Section titled “--rewrite”-r, --rewrite <FIX>
The code that replaces each match. Metavariables of the pattern are filled in.
--lang
Section titled “--lang”-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
Section titled “--debug-query”--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
Section titled “--follow”--follow
Follow symbolic links.
--no-ignore
Section titled “--no-ignore”--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
Section titled “--stdin”--stdin
Read the code from stdin, in the language of --lang.
--globs
Section titled “--globs”--globs <GLOBS>
Include or exclude paths that match a glob, as in .gitignore. ! excludes.
Give it more than once to pass several values.
--threads
Section titled “--threads”-j, --threads <NUM>
Threads to use. 0 lets ast-grep choose.
Default: 0.
--interactive
Section titled “--interactive”-i, --interactive
Confirm each rewrite, or edit the match in your editor.
--update-all
Section titled “--update-all”-U, --update-all
Apply every rewrite without asking.
--files-with-matches
Section titled “--files-with-matches”--files-with-matches
Print only the paths of files that match.
Cannot be combined with --interactive, --update-all, --json, --format.
--json
Section titled “--json”--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
Section titled “--format”--format <FORMAT>
Output format. Default: text on a terminal, json otherwise. JSON is one line.
Values: text, json.
--color
Section titled “--color”--color <WHEN>
When to color the text output.
Default: auto.
Values: auto, always, ansi, never.
--heading
Section titled “--heading”--heading <WHEN>
When to print the file name above its matches instead of before each one.
Default: auto.
Values: auto, always, never.
--after
Section titled “--after”-A, --after <NUM>
Lines to show after each match.
Default: 0. Cannot be combined with --context.
--before
Section titled “--before”-B, --before <NUM>
Lines to show before each match.
Default: 0. Cannot be combined with --context.
--context
Section titled “--context”-C, --context <NUM>
Lines to show around each match.
Default: 0.
--config
Section titled “--config”-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.
Examples
Section titled “Examples”$ xpd run --lang python --pattern '$X.iterrows()' samples/bad.py --format textsamples/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.
$ xpd query -p 'pd.merge($$$A)' -r 'df.merge(other, on="k")' samples/bad.py --format text --color neversamples/bad.py@@ -4,7 +4,7 @@5 5 │ for i, row in df.iterrows():6 6 │ df["a"][i] = row["a"] * 27 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.
$ 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 status
Section titled “Exit status”| Exit code | Meaning |
|---|---|
| 0 | Something matched |
| 1 | Nothing matched |
| 2 | xpd could not run |