본문으로 건너뛰기

소개

Markdown으로 보기 GitHub에서 수정 문서 위치 bfe242f

Pitmaster은 순수 PHP 라이브러리로, Git 저장소를 기본 기능으로 읽고 씁니다. 핵심 저장소 작업은 git 바이너리를 셸에서 실행하거나 FFI를 사용하지 않습니다. Git 객체 모델, pack 파일 형식, 인덱스 형식, smart HTTP 전송 방식을 PHP로 구현했습니다.

Pitmaster이 필요한 이유

Git 저장소와 상호작용하는 PHP 애플리케이션은 보통 git 바이너리를 셸에서 실행합니다. 이 방식은 작동하지만, git 설치 여부에 의존하고 exec() 및 proc_open()과 관련한 보안 우려를 낳으며, 제한된 환경(git이 없는 컨테이너, 공유 호스팅, 서버리스 함수)에서 애플리케이션을 배포하기 어렵게 만듭니다.

Pitmaster은 핵심 저장소 작업에 필요한 git 의존성을 제거합니다. PHP 애플리케이션은 PHP의 내장 함수만 사용해 커밋 기록을 읽고, 커밋을 만들고, diff를 계산하고, 상태를 확인하고, smart HTTP을 통해 원격 저장소에 푸시할 수 있습니다. 예외는 훅과 SSH 전송 방식입니다. 둘 다 프로세스를 시작하며, 저장소 핸들별로 비활성화할 수 있습니다(훅 참조).

기능

  • 느슨한 객체(blob, tree, commit, tag)를 읽고 씁니다
  • pack 파일을 읽고 델타 체인을 해석합니다(OFS_DELTA 및 REF_DELTA)
  • 네트워크 작업을 위한 pack 파일을 씁니다
  • 인덱스/스테이징 영역을 읽고 씁니다(v2, v3, v4 형식)
  • ref(branch, tag, HEAD, packed-refs, reftable)를 읽고 씁니다
  • git의 통합 형식으로 diff를 계산합니다(Myers, Patience, Histogram, Minimal 알고리즘)
  • 충돌을 감지하며 3방향 병합을 수행합니다
  • 커밋 그래프를 순회합니다(log, 조상 관계, 병합 기준점)
  • Git smart HTTP 프로토콜을 사용합니다(clone, fetch, push)
  • worktree, 하위 모듈, stash, 훅, Git LFS을 지원합니다

요구 사항

  • PHP 8.2 이상
  • zlib 확장(거의 모든 PHP 설치에 기본 포함)
  • json 확장
  • mbstring 확장(composer.json에 선언되어 있으므로 설치 시 Composer에 필요합니다)
  • ctype 확장(객체 해시 검증에 사용됩니다. 대부분의 PHP 빌드에서 활성화되어 있지만 composer.json에는 선언되지 않습니다)

핵심 저장소 작업에는 git 바이너리가 필요하지 않습니다. 선택 기능에는 추가 런타임 기능이 필요할 수 있습니다. 훅 실행에는 proc_open()이 사용되고, SSH 전송 방식은 ssh 시스템 바이너리를 proc_open()를 통해 시작하며, ext-ssh2이 로드된 경우에는 이를 사용합니다.

빠른 예제

PHP
use Pitmaster\Pitmaster;

$repo = Pitmaster::open('/path/to/project');

// Read the current HEAD commit
$head = $repo->head();
echo $head->message;

// List branches
foreach ($repo->branches() as $branch) {
    echo $branch . "\n";
}

// Check status
foreach ($repo->status() as $entry) {
    echo "{$entry->path}: {$entry->index->value}{$entry->worktree->value}\n";
}

// Create a commit
$repo->add('src/Feature.php');
$commitId = $repo->commit('Add new feature');

시작하기부터 살펴본 다음 나머지 기능은 API, CLI, 작업에서 확인하세요. 테스트에서는 Pitmaster을 git에 맞춰 검증하는 방법을 설명합니다.