Skip to content

cli.md

Latest commit

 

History

History
341 lines (267 loc) · 12.2 KB

cli.md

File metadata and controls

341 lines (267 loc) · 12.2 KB
Raw
title CLI
description Complete command reference for the greph, greph-index, rg, and sg executables.
path cli
order 160
section Reference
meta_title CLI
meta_description Complete command reference for the greph, greph-index, rg, and sg executables.

CLI Reference

Greph ships four executables. All four share the same engine; the difference is the surface they expose.

Binary Purpose
greph Native text search, AST search, and AST rewrite
greph-index Warmed text index, AST fact index, and cached AST search
rg ripgrep-style compatibility wrapper
sg ast-grep-style compatibility wrapper

All paths in the examples use ./vendor/bin/<binary>. Substitute ./bin/<binary> if you are working from a clone of the repository.

greph

Native text search, AST search, and AST rewrite.

greph [options] pattern [path...]
greph -p pattern [options] [path...]
greph -p pattern -r replacement [options] [path...]

If a path is omitted, the current directory is searched.

Text mode

Default mode. Patterns are PCRE2 regexes unless -F is set.

# Regex search
./vendor/bin/greph "function\s+\w+" src

# Fixed-string search
./vendor/bin/greph -F "function" src

# Case-insensitive whole-word with two lines of context
./vendor/bin/greph -F -i -w -C 2 "function" src

Output format matches grep -rn:

src/Greph.php:31:final class Greph
src/Greph.php:36:    public static function walk(...

AST mode

Activated by -p. Patterns are written as ordinary PHP with $VAR and $$$VARIADIC metavariables. See Modes / AST Search for the full pattern grammar.

./vendor/bin/greph -p 'new $CLASS()' src
./vendor/bin/greph -p '$obj->$method($$$ARGS)' src
./vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

Rewrite mode

Activated by combining -p with -r. The replacement template uses the same metavariables as the search pattern; captured nodes are spliced in by name.

# Preview only
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
./vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Options

Flag Meaning
-F Fixed-string search (no regex)
-i Case-insensitive matching
-w Whole-word matching
-v Invert match
-c Count matches per file
-l List matching file paths only
-L List non-matching file paths only
-h Suppress filename prefixes in text mode
-H Always print filename prefixes in text mode
-n Show line numbers (default: on)
-A N Show N lines after each match
-B N Show N lines before each match
-C N Show N lines of context before and after each match
-m N Stop after N matches per file
-j N Use N parallel workers
-p PATTERN AST search pattern
-r TEMPLATE AST rewrite template (requires -p)
--glob GLOB Include only files whose paths match GLOB
--type NAME Include a file type alias (php, js, md, ...)
--type-not NAME Exclude a file type alias
--lang NAME AST language. Default: php
--json Emit JSON output
--no-ignore Ignore .gitignore and .grephignore rules
--hidden Include hidden files
--dry-run Print rewrites without writing files
--interactive Confirm each rewritten file
--help Show inline usage

greph-index

Warmed text index, AST fact index, and cached AST search.

greph-index build [path] [--index-dir DIR]
greph-index refresh [path] [--index-dir DIR]
greph-index search [options] pattern [path...]

greph-index set build [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set refresh [manifest] [--manifest FILE] [--mode MODE] [--index NAME...]
greph-index set stats [manifest] [--manifest FILE] [--mode MODE] [--index NAME...] [--dry-refresh]
greph-index set search [options] pattern [path...]

greph-index ast-index build [path] [--index-dir DIR]
greph-index ast-index refresh [path] [--index-dir DIR]
greph-index ast-index search [options] pattern [path...]

greph-index ast-cache build [path] [--index-dir DIR]
greph-index ast-cache refresh [path] [--index-dir DIR]
greph-index ast-cache search [options] pattern [path...]

Text index

# Build (full)
./vendor/bin/greph-index build .

# Build with lifecycle policy
./vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

# Refresh (incremental: added, updated, deleted, unchanged)
./vendor/bin/greph-index refresh .

# Query
./vendor/bin/greph-index search -F "function" .
./vendor/bin/greph-index search -i -w "function" .
./vendor/bin/greph-index search -c "function" .
./vendor/bin/greph-index search --trace-plan -F "function" .
./vendor/bin/greph-index search -F "function" . \
  --index-dir core/.greph-index \
  --index-dir plugins/demo/.greph-index \
  --show-index-origin

The text index is a warmed trigram + identifier postings store. It lives at .greph-index/ in the indexed root by default.

Index sets

Index sets turn repeated multi-index workflows into a named manifest:

./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --dry-refresh
./vendor/bin/greph-index set search --show-index-origin -F "function" .
./vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
./vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

The default manifest file is .greph-index-set.json. Each entry points at a root, a mode, and a lifecycle profile. set build and set refresh operate on the enabled entries; set search fans out across the selected entries and de-duplicates overlapping matches.

AST fact index

./vendor/bin/greph-index ast-index build .
./vendor/bin/greph-index ast-index refresh .
./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src
./vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir core/.greph-ast-index \
  --index-dir plugins/demo/.greph-ast-index \
  --show-index-origin

The AST fact index extracts node-level facts (calls, instantiations, classes, methods) into a queryable store. Lookups are O(log n) on the fact key, then verified against the source. Stored at .greph-ast-index/ by default.

AST cache

./vendor/bin/greph-index ast-cache build .
./vendor/bin/greph-index ast-cache refresh .
./vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-cache search --trace-plan 'array($$$ITEMS)' src

The AST cache stores parsed trees on disk so searches skip the parser entirely. Stored at .greph-ast-cache/ by default.

Options

Text search options match the greph flag set (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Additional flags:

Flag Meaning
--index-dir DIR Use a non-default warmed index directory. Repeatable for multi-index search and stats.
--lifecycle PROFILE Build policy: static, manual-refresh, opportunistic-refresh, strict-stale-check
--auto-refresh-max-files N Opportunistic refresh file threshold
--auto-refresh-max-bytes N Opportunistic refresh byte threshold
--manifest FILE Load an index-set manifest. Default: .greph-index-set.json
--mode MODE Restrict set operations to text, ast-index, or ast-cache
--index NAME Restrict set operations to a named manifest entry. Repeatable.
--show-index-origin Prefix warmed multi-index or set output with the matching index entry name
--trace-plan Emit warmed planner diagnostics to stderr
--dry-refresh In stats, report what a warmed search would do without mutating anything
--lang NAME AST language for ast-index / ast-cache searches. Default: php
-j N, --jobs N Workers for AST scans
-l, --files-with-matches List matching file paths only (AST mode)
--strict-parse Fail on parse errors instead of skipping
--fallback MODE Missing-index behavior: fail (default) or scan
--help Show inline usage

rg

ripgrep-style compatibility wrapper. Supports the most commonly used ripgrep flags. The verified surface is published in the feature matrix.

rg [options] pattern [path...]
rg --files [options] [path...]

Examples

./vendor/bin/rg -F "function" src
./vendor/bin/rg --json -F "function" src
./vendor/bin/rg --files src
./vendor/bin/rg --files --type php .
./vendor/bin/rg --type-not js -F "function" .

Supported options

Flag Meaning
-F, --fixed-strings Fixed-string search
-i, --ignore-case Case-insensitive search
-w, --word-regexp Whole-word search
-v, --invert-match Invert matches
-c, --count Count matching lines
-l, --files-with-matches List matching files
--files-without-match List non-matching files
-I, --no-filename Suppress filename prefixes
-H, --with-filename Always print filename prefixes
-n, --line-number Show line numbers
-A N, --after-context N Show N lines after each match
-B N, --before-context N Show N lines before each match
-C N, --context N Show N lines before and after each match
-m N, --max-count N Stop after N matches per file
-j N, --threads N Use N parallel workers
-e P, --regexp P Search pattern
-L, --follow Follow symlinks
--glob GLOB Include only files whose paths match GLOB
--type NAME Include a file type
--type-not NAME Exclude a file type
--json Emit ripgrep-style JSON events
--no-ignore Ignore .gitignore and .grephignore rules
--hidden Include hidden files
--files List candidate files instead of searching
--help Show inline usage

sg

ast-grep-style compatibility wrapper. Supports the most commonly used ast-grep flags. The verified surface is published in the feature matrix.

sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]

run is the canonical ast-grep verb. scan and rewrite are wrapper-only aliases that mirror common usage. A bare invocation (sg --pattern ... .) also works as a one-shot search.

Examples

./vendor/bin/sg run --pattern 'array($$$ITEMS)' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src/App.php
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src/App.php
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src/App.php
./vendor/bin/sg scan -p 'array($$$ITEMS)' src/App.php
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src/App.php

Supported options

Flag Meaning
-p, --pattern PATTERN AST pattern
-r, --rewrite TEMPLATE Rewrite template
-l, --lang NAME AST language. Default: php
-j, --threads N Use N parallel workers
-i, --interactive Confirm each rewrite
-U, --update-all Apply rewrites without confirmation
--files-with-matches Print only file paths with matches
--json[=STYLE] Emit JSON output. STYLE = pretty, stream, or compact
--no-ignore [MODE] Ignore repository ignore rules
--hidden Include hidden files
--glob GLOB, --globs GLOB Include only files whose paths match GLOB
--type NAME Include a file type
--type-not NAME Exclude a file type
--dry-run Preview rewrites without writing files
--help Show inline usage

Exit codes

Greph follows grep / ripgrep conventions:

Code Meaning
0 At least one match was found (or, for rewrites, at least one file changed)
1 No matches found
2 Usage error or runtime failure (bad arguments, missing index, parse error in --strict-parse mode)