Справочник за CLI

Преглед като Markdown Редактиране в GitHub Документация за d105217

Greph включва четири изпълними файла. И четирите използват една и съща машина; разликата е в интерфейса, който предоставят.

Изпълним файл	Предназначение
`greph`	Търсене в обикновен текст, AST търсене и AST пренаписване
`greph-index`	Загрят текстов индекс, индекс на AST факти и кеширано AST търсене
`rg`	Обвивка за съвместимост в стил ripgrep
`sg`	Обвивка за съвместимост в стил ast-grep

Всички пътища в примерите използват ./vendor/bin/<binary>, който работи с Greph 0.2.3 или по-нова версия, инсталирана като зависимост. Заменете с ./bin/<binary>, ако работите с клонирано хранилище.

`greph`

Търсене в обикновен текст, AST търсене и AST пренаписване.

Обвивка

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

Ако пътят бъде пропуснат, се търси в текущата директория.

Текстов режим

Режимът по подразбиране. Шаблоните са PCRE2 регулярни изрази, освен ако не е зададено -F.

Обвивка

# 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

Форматът на изхода съвпада с grep -rn:

Text

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

AST режим

Активира се с -p. Шаблоните се записват като обикновен PHP с метапроменливи $VAR и $$$VARIADIC. Вижте Режими / AST търсене за пълната граматика на шаблоните.

Обвивка

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

Режим на пренаписване

Активира се чрез комбиниране на -p с -r. Шаблонът за замяна използва същите метапроменливи като шаблона за търсене; уловените възли се вмъкват по име.

Обвивка

# 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

Опции

Флаг	Значение
`-F`	Търсене по точен низ (без регулярен израз)
`-i`	Съвпадение без разлика между главни и малки букви
`-w`	Съвпадение на цели думи
`-v`	Обръщане на съвпадението
`-c`	Брой съвпадения във всеки файл
`-l`	Показване само на пътищата към файловете със съвпадения
`-L`	Показване само на пътищата към файловете без съвпадения
`-h`	Потискане на префиксите с имена на файлове в текстов режим
`-H`	Винаги показване на префиксите с имена на файлове в текстов режим
`-n`	Показване на номерата на редовете (по подразбиране: включено)
`-A N`	Показване на N реда след всяко съвпадение
`-B N`	Показване на N реда преди всяко съвпадение
`-C N`	Показване на N реда контекст преди и след всяко съвпадение
`-m N`	Спиране след N съвпадения във всеки файл
`-j N`	Използване на N паралелни работници
`-p PATTERN`	Шаблон за AST търсене
`-r TEMPLATE`	Шаблон за AST пренаписване (изисква `-p`)
`--glob GLOB`	Включване само на файлове, чиито пътища съвпадат с GLOB
`--type NAME`	Включване на псевдоним за тип файл (`php`, `js`, `md`, ...)
`--type-not NAME`	Изключване на псевдоним за тип файл
`--lang NAME`	Език за AST. По подразбиране: `php`
`--json`	Извеждане на изход във формат JSON
`--no-ignore`	Игнориране на правилата `.gitignore` и `.grephignore`
`--hidden`	Включване на скритите файлове
`--dry-run`	Показване на пренаписванията, без записване във файловете
`--interactive`	Потвърждаване на всеки пренаписан файл
`--help`	Показване на кратките инструкции за употреба

`greph-index`

Загрят текстов индекс, индекс на AST факти и кеширано AST търсене.

Обвивка

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

Текстов индекс

Обвивка

# 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

Текстовият индекс е предварително заредено хранилище от триграми и списъци с идентификатори. По подразбиране се намира в .greph-index/ в индексирания корен.

Набори от индекси

Наборите от индекси превръщат повтарящите се работни процеси с множество индекси в именуван манифест:

Обвивка

./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)' .

Файлът с манифеста по подразбиране е .greph-index-set.json. Всеки запис сочи към корен, режим и профил на жизнения цикъл. set build и set refresh работят с активираните записи; set search изпълнява търсенето във всички избрани записи и премахва дублиращите се съвпадения.

Индекс на AST факти

Обвивка

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

Индексът на AST факти извлича факти на ниво възел (извиквания, инстанции, класове, методи) в хранилище с възможност за заявки. Търсенето първо използва O(log n) по ключа на факта, след което проверява резултатите спрямо изходния код. По подразбиране се съхранява в .greph-ast-index/.

AST кеш

Обвивка

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

AST кешът съхранява анализираните дървета на диска, така че търсенията да пропускат изцяло анализатора. По подразбиране се съхранява в .greph-ast-cache/.

Опции

Опциите за текстово търсене съответстват на набора от флагове greph (-F, -i, -w, -v, -c, -l, -L, -A, -B, -C, -m, --glob, --type, --type-not, --json, --no-ignore, --hidden).

Допълнителни флагове:

Флаг	Значение
`--index-dir DIR`	Използване на нестандартна директория за предварително зареден индекс. Може да се повтаря при търсене и статистика с множество индекси.
`--lifecycle PROFILE`	Правило за изграждане: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
`--auto-refresh-max-files N`	Праг за броя файлове при периодично обновяване
`--auto-refresh-max-bytes N`	Праг за размера в байтове при периодично обновяване
`--manifest FILE`	Зареждане на манифест за набор от индекси. По подразбиране: `.greph-index-set.json`
`--mode MODE`	Ограничаване на операциите с набори до `text`, `ast-index` или `ast-cache`
`--index NAME`	Ограничаване на операциите с набори до запис с име в манифеста. Може да се повтаря.
`--show-index-origin`	Добавяне на името на съответния запис в набора към изхода от търсене или набор с множество загрети индекси
`--trace-plan`	Извеждане на диагностичните данни на загретия планировчик в `stderr`
`--dry-refresh`	В `stats` докладване на действията на загрятото търсене, без промяна на каквото и да било
`--lang NAME`	Език за AST при търсения `ast-index` / `ast-cache`. По подразбиране: `php`
`-j N`, `--jobs N`	Работници за AST сканиране
`-l`, `--files-with-matches`	Показване само на пътищата към файловете със съвпадения (AST режим)
`--strict-parse`	Прекратяване при грешки при анализиране вместо пропускането им
`--fallback MODE`	Поведение при липсващ индекс: `fail` (по подразбиране) или `scan`
`--help`	Показване на кратките инструкции за употреба

`rg`

Обвивка за съвместимост в стил ripgrep. Поддържа най-често използваните флагове на ripgrep. Потвърденият обхват е публикуван в матрицата на функциите.

Обвивка

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

Примери

Обвивка

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

Поддържани опции

Флаг	Значение
`-F`, `--fixed-strings`	Търсене по точен низ
`-i`, `--ignore-case`	Търсене без разлика между главни и малки букви
`-w`, `--word-regexp`	Търсене на цели думи
`-v`, `--invert-match`	Обръщане на съвпаденията
`-c`, `--count`	Брой редове със съвпадения
`-l`, `--files-with-matches`	Показване на файловете със съвпадения
`--files-without-match`	Показване на файловете без съвпадения
`-I`, `--no-filename`	Потискане на префиксите с имена на файлове
`-H`, `--with-filename`	Винаги показване на префиксите с имена на файлове
`-n`, `--line-number`	Показване на номерата на редовете
`-A N`, `--after-context N`	Показване на N реда след всяко съвпадение
`-B N`, `--before-context N`	Показване на N реда преди всяко съвпадение
`-C N`, `--context N`	Показване на N реда преди и след всяко съвпадение
`-m N`, `--max-count N`	Спиране след N съвпадения във всеки файл
`-j N`, `--threads N`	Използване на N паралелни работници
`-e P`, `--regexp P`	Шаблон за търсене
`-L`, `--follow`	Следване на символни връзки
`--glob GLOB`	Включване само на файлове, чиито пътища съвпадат с GLOB
`--type NAME`	Включване на тип файл
`--type-not NAME`	Изключване на тип файл
`--json`	Извеждане на събития във формат ripgrep с форма на JSON
`--no-ignore`	Игнориране на правилата `.gitignore` и `.grephignore`
`--hidden`	Включване на скритите файлове
`--files`	Изброяване на файловете-кандидати вместо търсене
`--help`	Показване на кратките инструкции за употреба

`sg`

Обвивка за съвместимост в стил ast-grep. Поддържа най-често използваните флагове на ast-grep. Потвърденият обхват е публикуван в матрицата на функциите.

Обвивка

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

run е основната команда ast-grep. scan и rewrite са псевдоними само за обвивката, които отразяват обичайната употреба. Работи и самостоятелно извикване (sg --pattern ... .) за еднократно търсене.

Примери

Обвивка

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

Поддържани опции

Флаг	Значение
`-p`, `--pattern PATTERN`	AST шаблон
`-r`, `--rewrite TEMPLATE`	Шаблон за пренаписване
`-l`, `--lang NAME`	Език за AST. По подразбиране: `php`
`-j`, `--threads N`	Използване на N паралелни работници
`-i`, `--interactive`	Потвърждаване на всяко пренаписване
`-U`, `--update-all`	Прилагане на пренаписванията без потвърждение
`--files-with-matches`	Показване само на пътищата към файлове със съвпадения
`--json[=STYLE]`	Извеждане във формат JSON. STYLE = `pretty`, `stream` или `compact`
`--no-ignore [MODE]`	Игнориране на правилата за игнориране на хранилището
`--hidden`	Включване на скритите файлове
`--glob GLOB`, `--globs GLOB`	Включване само на файлове, чиито пътища съвпадат с GLOB
`--type NAME`	Включване на тип файл
`--type-not NAME`	Изключване на тип файл
`--dry-run`	Преглед на пренаписванията без записване във файловете
`--help`	Показване на кратките инструкции за употреба

Кодове за изход

Greph следва конвенциите на grep / ripgrep:

Код	Значение
`0`	Намерено е поне едно съвпадение (или при пренаписване е променен поне един файл)
`1`	Не са намерени съвпадения
`2`	Грешка при употреба или изпълнение (невалидни аргументи, липсващ индекс, грешка при анализиране в режим `--strict-parse`)