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

경로를 생략하면 현재 디렉터리를 검색합니다.

텍스트 모드

기본 모드입니다. -F을 설정하지 않으면 패턴은 PCRE2 정규식으로 처리됩니다.

셸

# 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-index` / `ast-cache` 검색의 AST 언어. 기본값: `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` 모드의 파싱 오류)