본문으로 건너뛰기

Git 워크트리

Hermes 에이전트는 종종 크고 오래 지속되는 저장소에서 사용됩니다. 다음과 같은 경우:

  • 같은 프로젝트에서 여러 에이전트를 병렬로 실행하고 싶거나
  • 실험적인 리팩터를 main 브랜치와 분리하여 유지하고 싶다면

Git 워크트리는 저장소 전체를 복제하지 않고 각 에이전트에 자체 체크아웃을 제공하는 가장 안전한 방법입니다.

이 페이지에서는 워크트리를 Hermes와 결합하여 각 세션에 깨끗하고 격리된 작업 디렉터리를 갖는 방법을 보여줍니다.

Hermes와 함께 워크트리를 사용하는 이유는?​

Hermes는 현재 작업 디렉토리를 프로젝트 루트로 취급합니다:

  • CLI: hermes 또는 hermes chat 을 실행하는 디렉토리
  • 메시징 게이트웨이: MESSAGING_CWD가 설정한 디렉토리

동일한 체크아웃에서 여러 에이전트를 실행하면, 서로의 변경 사항이 서로에게 영향을 줄 수 있습니다:

  • 한 에이전트가 다른 에이전트가 사용 중인 파일을 삭제하거나 다시 쓸 수 있습니다.
  • 어떤 변화가 어떤 실험에 속하는지 이해하기가 더 어려워진다.

워크트리로 각 에이전트는 다음을 받습니다:

  • 자체 브랜치 및 작업 디렉토리
  • /rollback의 자체 체크포인트 관리자 기록

또한 참조: 체크포인트 및 /롤백.

빠른 시작: 작업 트리 만들기​

주 저장소(.git/ 포함)에서 기능 브랜치를 위한 새로운 워크트리를 생성하세요:

# From the main repo root
cd /path/to/your/repo

# Create a new branch and worktree in../repo-feature
git worktree add../repo-feature feature/hermes-experiment

이것은 다음을 생성합니다:

  • 새 디렉토리: ../repo-feature
  • 새 브랜치: feature/hermes-experiment 해당 디렉토리에서 체크아웃됨

이제 새 워크트리로 cd 하고 거기에서 Hermes를 실행할 수 있습니다:

cd../repo-feature

# Start Hermes in the worktree
hermes

헤르메스는 다음을 할 것입니다:

  • 프로젝트 루트로 ../repo-feature를 참조하세요.
  • 해당 디렉토리를 컨텍스트 파일, 코드 편집 및 도구용으로 사용하세요.
  • 이 작업 트리에 범위가 지정된 /rollback에 대해 별도의 체크포인트 기록을 사용하세요.

여러 에이전트를 병렬로 실행하기​

각각 고유한 브랜치를 가진 여러 작업 트리를 생성할 수 있습니다:

cd /path/to/your/repo

git worktree add../repo-experiment-a feature/hermes-a
git worktree add../repo-experiment-b feature/hermes-b

각각의 터미널에서:

# Terminal 1
cd../repo-experiment-a
hermes

# Terminal 2
cd../repo-experiment-b
hermes

각 Hermes 프로세스:

  • 자신의 브랜치에서 작동합니다 (feature/hermes-a 대 feature/hermes-b).
  • 작업 트리 경로에서 파생된 다른 섀도우 저장소 해시 아래에 체크포인트를 작성합니다.
  • /rollback를 다른 것에 영향을 주지 않고 독립적으로 사용할 수 있습니다.

이것은 특히 다음과 같은 경우에 유용합니다:

  • 배치 리팩터 실행 중.
  • 같은 작업에 대해 다양한 접근 방식을 시도하기.
  • 동일한 업스트림 저장소에 대해 CLI + 게이트웨이 세션을 페어링합니다.

작업 트리를 안전하게 정리하기​

실험을 마쳤을 때:

  1. 작품을 보관할지 버릴지 결정하세요.
  2. 그것을 유지하고 싶다면:
    • 브랜치를 평소처럼 main 브랜치에 병합하세요.
  3. 워크트리를 제거하세요:
cd /path/to/your/repo

# Remove the worktree directory and its reference
git worktree remove../repo-feature

노트:

  • git worktree remove는 강제로 하지 않는 한, 커밋되지 않은 변경 사항이 있는 워크트리를 제거하는 것을 거부합니다.
  • 워크트리를 제거해도 브랜치는 자동으로 삭제되지 않습니다; 브랜치는 일반 git branch 명령을 사용하여 삭제하거나 유지할 수 있습니다.
  • ~/.hermes/checkpoints/ 아래의 Hermes 체크포인트 데이터는 워크트리를 제거해도 자동으로 정리되지 않지만, 보통 매우 작습니다.

최상의 실행 방법​

  • Hermes 실험당 하나의 워크트리
    • 각 중요한 변경 사항마다 전용 브랜치/워크트리를 생성하세요.
    • 이것은 변경 사항을 집중시키고 PR을 작고 검토하기 쉽게 유지합니다.
  • 실험 후 가지에 이름을 붙이세요
    • 예: feature/hermes-checkpoints-docs, feature/hermes-refactor-tests.
  • 자주 커밋하기
    • 높은 수준의 이정표에는 git 커밋을 사용하세요.
    • 도구 기반 편집 중 안전망으로 체크포인트 및 /롤백을 사용하세요.
  • 워크트리를 사용할 때는 빈 저장소 루트에서 Hermes를 실행하지 마세요
    • 각 에이전트가 명확한 범위를 가지도록 작업 트리 디렉토리를 대신 선호하세요.

hermes -w 사용 (자동 워크트리 모드)​

Hermes에는 자체 브랜치가 있는 일회용 git 작업트리를 자동으로 생성하는 내장 -w 플래그가 있습니다. 작업트리를 수동으로 설정할 필요 없이 — 그냥 cd를 저장소에 넣고 실행하면 됩니다:

cd /path/to/your/repo
hermes -w

헤르메스는 다음을 할 것입니다:

  • 레포 안의 .worktrees/ 아래에 임시 작업 트리를 만드세요.
  • 격리된 브랜치(e.g. hermes/hermes-<hash>)를 확인하세요.
  • 해당 작업 트리 안에서 전체 CLI 세션을 실행하세요.

이것이 워크트리 격리를 얻는 가장 쉬운 방법입니다. 단일 쿼리와 결합할 수도 있습니다:

hermes -w -q "Fix issue #123"

병렬 에이전트의 경우, 여러 터미널을 열고 각 터미널에서 hermes -w를 실행하세요 — 각 실행은 자동으로 자신의 워크트리와 브랜치를 갖습니다.

모든 것을 하나로 합치기​

  • 각 Hermes 세션에 자체적인 깨끗한 체크아웃을 제공하려면 git worktrees를 사용하세요.
  • 브랜치를 사용하여 실험의 고수준 기록을 캡처하세요.
  • 각 워크트리 내에서 실수를 복구하려면 **checkpoints + /rollback**를 사용하세요.

이 조합은 당신에게 다음을 제공합니다:

  • 서로 다른 에이전트와 실험이 서로 간섭하지 않도록 하는 강력한 보장.
  • 잘못된 편집에서 쉽게 복구할 수 있는 빠른 반복 주기.
  • 깔끔하고 검토 가능한 풀 리퀘스트.