Довідник 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`)