# Dokumentacja CLI

Greph zawiera cztery pliki wykonywalne. Wszystkie korzystają z tego samego silnika; różnią się udostępnianym interfejsem.

| Plik wykonywalny | Zastosowanie |
|---|---|
| `greph` | Natywne wyszukiwanie tekstu, wyszukiwanie AST i przepisywanie AST |
| `greph-index` | Rozgrzany indeks tekstowy, indeks faktów AST i buforowane wyszukiwanie AST |
| `rg` | Warstwa zgodności w stylu ripgrep |
| `sg` | Warstwa zgodności w stylu ast-grep |

W przykładach użyto ścieżki `./vendor/bin/<binary>`, która działa z Greph 0.2.3 lub nowszą wersją zainstalowaną jako zależność. Jeśli pracujesz na klonie repozytorium, zastąp ją przez `./bin/<binary>`.

---

## `greph`

Natywne wyszukiwanie tekstu, wyszukiwanie AST i przepisywanie AST.

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

Jeśli pominięto ścieżkę, wyszukiwanie odbywa się w bieżącym katalogu.

### Tryb tekstowy

Tryb domyślny. Wzorce są wyrażeniami regularnymi PCRE2, chyba że ustawiono `-F`.

```bash
# 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
```

Format wyjściowy odpowiada formatowi `grep -rn`:

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

### Tryb AST

Aktywowany przez `-p`. Wzorce zapisuje się jako zwykłe PHP z metazmiennymi `$VAR` i `$$$VARIADIC`. Pełną składnię wzorców opisano w sekcji [Tryby / wyszukiwanie AST](https://greph.inline0.dev/pl/docs/modes/ast).

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

### Tryb przepisywania

Aktywowany przez połączenie `-p` z `-r`. Szablon zastępczy używa tych samych metazmiennych co wzorzec wyszukiwania; przechwycone węzły są wstawiane według nazwy.

```bash
# 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
```

### Opcje

| Flaga | Znaczenie |
|---|---|
| `-F` | Wyszukiwanie stałego ciągu (bez wyrażeń regularnych) |
| `-i` | Dopasowywanie bez rozróżniania wielkości liter |
| `-w` | Dopasowywanie całych słów |
| `-v` | Odwrócenie dopasowania |
| `-c` | Zliczanie dopasowań w każdym pliku |
| `-l` | Wyświetlanie tylko ścieżek pasujących plików |
| `-L` | Wyświetlanie tylko ścieżek niepasujących plików |
| `-h` | Ukrywanie prefiksów nazw plików w trybie tekstowym |
| `-H` | Zawsze wyświetlanie prefiksów nazw plików w trybie tekstowym |
| `-n` | Wyświetlanie numerów wierszy (domyślnie: włączone) |
| `-A N` | Wyświetlanie N wierszy po każdym dopasowaniu |
| `-B N` | Wyświetlanie N wierszy przed każdym dopasowaniem |
| `-C N` | Wyświetlanie N wierszy kontekstu przed każdym dopasowaniem i po nim |
| `-m N` | Zatrzymanie po N dopasowaniach w każdym pliku |
| `-j N` | Użycie N równoległych procesów roboczych |
| `-p PATTERN` | Wzorzec wyszukiwania AST |
| `-r TEMPLATE` | Szablon przepisywania AST (wymaga `-p`) |
| `--glob GLOB` | Uwzględnianie tylko plików, których ścieżki pasują do GLOB |
| `--type NAME` | Uwzględnienie aliasu typu pliku (`php`, `js`, `md`, ...) |
| `--type-not NAME` | Wykluczenie aliasu typu pliku |
| `--lang NAME` | Język AST. Domyślnie: `php` |
| `--json` | Emitowanie danych wyjściowych JSON |
| `--no-ignore` | Ignorowanie reguł `.gitignore` i `.grephignore` |
| `--hidden` | Uwzględnianie ukrytych plików |
| `--dry-run` | Wyświetlanie przepisanych treści bez zapisywania plików |
| `--interactive` | Potwierdzanie każdego przepisanego pliku |
| `--help` | Wyświetlanie wbudowanej pomocy |

---

## `greph-index`

Rozgrzany indeks tekstowy, indeks faktów AST i buforowane wyszukiwanie AST.

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

### Indeks tekstowy

```bash
# 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
```

Indeks tekstowy to rozgrzany magazyn trójek i postów identyfikatorów. Domyślnie znajduje się w `.greph-index/` w indeksowanym katalogu głównym.

### Zestawy indeksów

Zestawy indeksów pozwalają zastąpić powtarzane operacje na wielu indeksach nazwanym manifestem:

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

Domyślny plik manifestu to `.greph-index-set.json`. Każdy wpis wskazuje katalog główny, tryb i profil cyklu życia. `set build` i `set refresh` działają na włączonych wpisach; `set search` uruchamia operację dla wybranych wpisów i usuwa zduplikowane nakładające się wyniki.

### Indeks faktów AST

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

Indeks faktów AST wyodrębnia fakty na poziomie węzłów (wywołania, instancje, klasy, metody) do przeszukiwalnego magazynu. Wyszukiwanie odbywa się przez O(log n) po kluczu faktu, a następnie wyniki są weryfikowane względem źródła. Domyślnie dane są przechowywane w `.greph-ast-index/`.

### Bufor AST

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

Bufor AST zapisuje sparsowane drzewa na dysku, dzięki czemu wyszukiwanie całkowicie pomija parser. Domyślnie dane są przechowywane w `.greph-ast-cache/`.

### Opcje

Opcje wyszukiwania tekstowego odpowiadają zestawowi flag `greph` (`-F`, `-i`, `-w`, `-v`, `-c`, `-l`, `-L`, `-A`, `-B`, `-C`, `-m`, `--glob`, `--type`, `--type-not`, `--json`, `--no-ignore`, `--hidden`).

Dodatkowe flagi:

| Flaga | Znaczenie |
|---|---|
| `--index-dir DIR` | Użycie niestandardowego katalogu rozgrzanego indeksu. Można powtarzać przy wyszukiwaniu i wyświetlaniu statystyk z wielu indeksów. |
| `--lifecycle PROFILE` | Zasady budowania: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check` |
| `--auto-refresh-max-files N` | Próg liczby plików dla odświeżania przy okazji |
| `--auto-refresh-max-bytes N` | Próg bajtów dla odświeżania przy okazji |
| `--manifest FILE` | Wczytanie manifestu zestawu indeksów. Domyślnie: `.greph-index-set.json` |
| `--mode MODE` | Ograniczenie operacji na zestawie do `text`, `ast-index` lub `ast-cache` |
| `--index NAME` | Ograniczenie operacji na zestawie do wskazanego wpisu manifestu. Można powtarzać. |
| `--show-index-origin` | Dodanie na początku danych wyjściowych wyszukiwania lub zestawu wielu rozgrzanych indeksów nazwy pasującego wpisu indeksu |
| `--trace-plan` | Emitowanie diagnostyki planisty rozgrzanego indeksu do `stderr` |
| `--dry-refresh` | W `stats` raportowanie działania wyszukiwania z rozgrzanym indeksem bez wprowadzania zmian |
| `--lang NAME` | Język AST dla wyszukiwań `ast-index` / `ast-cache`. Domyślnie: `php` |
| `-j N`, `--jobs N` | Procesy robocze do skanowania AST |
| `-l`, `--files-with-matches` | Wyświetlanie tylko ścieżek pasujących plików (tryb AST) |
| `--strict-parse` | Zgłaszanie błędów parsowania zamiast ich pomijania |
| `--fallback MODE` | Zachowanie przy braku indeksu: `fail` (domyślnie) lub `scan` |
| `--help` | Wyświetlanie wbudowanej pomocy |

---

## `rg`

Warstwa zgodności w stylu ripgrep. Obsługuje najczęściej używane flagi ripgrep. Zweryfikowany zakres opisano w [macierzy funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix).

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

### Przykłady

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

### Obsługiwane opcje

| Flaga | Znaczenie |
|---|---|
| `-F`, `--fixed-strings` | Wyszukiwanie stałego ciągu |
| `-i`, `--ignore-case` | Wyszukiwanie bez rozróżniania wielkości liter |
| `-w`, `--word-regexp` | Wyszukiwanie całych słów |
| `-v`, `--invert-match` | Odwrócenie dopasowań |
| `-c`, `--count` | Zliczanie pasujących wierszy |
| `-l`, `--files-with-matches` | Wyświetlanie pasujących plików |
| `--files-without-match` | Wyświetlanie niepasujących plików |
| `-I`, `--no-filename` | Ukrywanie prefiksów nazw plików |
| `-H`, `--with-filename` | Zawsze wyświetlanie prefiksów nazw plików |
| `-n`, `--line-number` | Wyświetlanie numerów wierszy |
| `-A N`, `--after-context N` | Wyświetlanie N wierszy po każdym dopasowaniu |
| `-B N`, `--before-context N` | Wyświetlanie N wierszy przed każdym dopasowaniem |
| `-C N`, `--context N` | Wyświetlanie N wierszy przed każdym dopasowaniem i po nim |
| `-m N`, `--max-count N` | Zatrzymanie po N dopasowaniach w każdym pliku |
| `-j N`, `--threads N` | Użycie N równoległych procesów roboczych |
| `-e P`, `--regexp P` | Wzorzec wyszukiwania |
| `-L`, `--follow` | Podążanie za dowiązaniami symbolicznymi |
| `--glob GLOB` | Uwzględnianie tylko plików, których ścieżki pasują do GLOB |
| `--type NAME` | Uwzględnianie typu pliku |
| `--type-not NAME` | Wykluczanie typu pliku |
| `--json` | Emitowanie zdarzeń ripgrep w stylu JSON |
| `--no-ignore` | Ignorowanie reguł `.gitignore` i `.grephignore` |
| `--hidden` | Uwzględnianie ukrytych plików |
| `--files` | Wyświetlanie plików kandydujących zamiast wyszukiwania |
| `--help` | Wyświetlanie wbudowanej pomocy |

---

## `sg`

Warstwa zgodności w stylu ast-grep. Obsługuje najczęściej używane flagi ast-grep. Zweryfikowany zakres opisano w [macierzy funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix).

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

`run` to kanoniczne polecenie ast-grep. `scan` i `rewrite` to aliasy dostępne wyłącznie w warstwie zgodności, odzwierciedlające typowe użycie. Działa też samo wywołanie (`sg --pattern ... .`), które uruchamia jednorazowe wyszukiwanie.

### Przykłady

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

### Obsługiwane opcje

| Flaga | Znaczenie |
|---|---|
| `-p`, `--pattern PATTERN` | Wzorzec AST |
| `-r`, `--rewrite TEMPLATE` | Szablon przepisywania |
| `-l`, `--lang NAME` | Język AST. Domyślnie: `php` |
| `-j`, `--threads N` | Użycie N równoległych procesów roboczych |
| `-i`, `--interactive` | Potwierdzanie każdego przepisania |
| `-U`, `--update-all` | Zastosowanie przepisań bez potwierdzenia |
| `--files-with-matches` | Wyświetlanie tylko ścieżek plików z dopasowaniami |
| `--json[=STYLE]` | Emitowanie danych wyjściowych JSON. STYLE = `pretty`, `stream` lub `compact` |
| `--no-ignore [MODE]` | Ignorowanie reguł ignorowania repozytorium |
| `--hidden` | Uwzględnianie ukrytych plików |
| `--glob GLOB`, `--globs GLOB` | Uwzględnianie tylko plików, których ścieżki pasują do GLOB |
| `--type NAME` | Uwzględnianie typu pliku |
| `--type-not NAME` | Wykluczanie typu pliku |
| `--dry-run` | Podgląd przepisań bez zapisywania plików |
| `--help` | Wyświetlanie wbudowanej pomocy |

---

## Kody wyjścia

Greph stosuje konwencje grep / ripgrep:

| Kod | Znaczenie |
|---|---|
| `0` | Znaleziono co najmniej jedno dopasowanie (lub w przypadku przepisywania zmieniono co najmniej jeden plik) |
| `1` | Nie znaleziono dopasowań |
| `2` | Błąd użycia lub błąd w czasie działania (nieprawidłowe argumenty, brak indeksu, błąd parsowania w trybie `--strict-parse`) |