Справочник 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`)