OpenCode Worktree 가이드: Git으로 코딩 작업 분리하기

Git worktree는 같은 저장소에 연결된 또 하나의 작업 디렉터리입니다. 기본 checkout은 main에 두고 옆 폴더에서 work/auth를 checkout할 수 있습니다. 폴더의 파일과 현재 브랜치는 각각 분리되지만 Git 객체와 이력은 공유하므로 작업마다 전체 저장소를 복제할 필요는 보통 없습니다.

이 흐름에는 OpenCode 전용 worktree 모드가 필요하지 않습니다. 새 디렉터리에서 CLI를 시작하면 해당 위치가 프로젝트 컨텍스트가 됩니다. 전역 설정은 계속 적용될 수 있지만 추적되지 않은 파일이나 로컬 환경 설정은 자동으로 복사되지 않습니다.

먼저 현재 checkout의 브랜치와 변경을 확인하세요. 깨끗한 상태에서 시작하면 새 작업에서 생긴 차이를 구분하기 쉽습니다. 저장소 루트에서 새 브랜치와 worktree를 함께 만들고, 원래 저장소 바깥의 형제 폴더에 checkout하세요.

예시 명령은 현재 commit에서 work/auth를 만들어 ../app-auth에 둡니다. 브랜치가 이미 있다면 다른 worktree에서 checkout 중인지 확인한 뒤 재사용하세요. Git은 같은 브랜치를 여러 연결 worktree에서 동시에 활성화하는 것을 보통 막습니다.

기본 저장소 루트에서 실행하세요. 새 브랜치는 현재 commit에서 시작합니다.

git status --short --branch
git worktree add -b work/auth ../app-auth
cd ../app-auth
opencode
git worktree list
git -C ../app-auth status --short --branch

cd ../app-auth 다음 해당 셸에서 opencode를 실행하세요. 현재 디렉터리가 중요한 경계입니다. worktree마다 별도 터미널이나 세션을 열고 파일 수정 전에 프로젝트 루트를 확인하세요. 처음에는 브랜치와 확인할 파일을 요약시키는 읽기 전용 요청이 좋습니다.

세션마다 범위가 좁은 작업을 지정하고 브랜치 이름을 기록하세요. 한 작업은 인증 테스트, 다른 작업은 문서를 맡을 수 있습니다. 두 세션이 같은 파일이나 생성 폴더를 동시에 수정하지 않게 하세요. 디렉터리 분리는 충돌을 줄일 뿐 에이전트를 자동으로 조정하지 않습니다.

worktree는 Git 파일과 index를 분리하지만 컨테이너나 보안 경계는 아닙니다. 로컬 DB, 테스트 서버, 캐시, Docker 프로젝트, 외부 계정은 세션들이 공유할 수 있습니다. 필요한 경우 DB/schema, 포트, 프로젝트 이름 또는 일회용 환경을 분리하세요.

Git은 선택한 commit에서 추적 파일을 checkout합니다. .env, 인증서, 캐시, 빌드 출력 같은 미추적·ignore 파일은 새 worktree에 없을 수 있습니다. 필요한 환경만 다시 준비하고 승인된 방식으로 비밀 정보를 불러오세요. 작업 전후 git status --short --branch를 확인합니다.

worktree 브랜치를 독립 변경으로 리뷰하세요. git diff를 확인하고 해당 디렉터리에서 프로젝트 검사를 실행한 뒤 의도한 파일만 있는지 확인합니다. 테스트가 통과하면 팀의 일반 절차로 병합하거나 rebase하세요. commit을 공유하기 전까지 다른 checkout에는 변경이 나타나지 않습니다.

삭제 전에 미커밋 변경을 살펴보고 commit, stash 또는 보관 중 하나를 결정하세요. git worktree remove ../app-auth는 깨끗한 연결 checkout을 지웁니다. 변경이 남으면 force 없이는 Git이 거부합니다. force를 일상 정리에 쓰지 마세요. git worktree prune은 오래된 등록만 정리합니다.

작업별 브랜치, 파일 스냅샷 또는 며칠 동안 유지할 리뷰 경계가 필요할 때 worktree를 사용하세요. 읽기 전용 조사나 미커밋 파일을 그대로 확인해야 하는 작업에는 같은 checkout의 다른 세션이 더 단순합니다. 순차 작업이고 한 폴더만 필요하면 브랜치만 전환하면 됩니다.

worktree를 쓰면 브랜치 이름, 의존성 설정, 서비스 분리, 테스트, 병합, 삭제를 관리해야 합니다. 여러 에이전트가 같은 파일을 수정한다면 최종 병합이 더 어려워질 수 있습니다. 작업을 겹치지 않게 나누거나 수정을 순서대로 실행하세요.

git worktree add가 브랜치가 이미 checkout됐다고 알리면 git worktree list를 확인하고 새 브랜치를 만들거나 기존 worktree로 돌아가세요. OpenCode 파일이 예상과 다르면 설정을 바꾸기 전에 터미널 위치와 프로젝트 루트를 확인합니다. ignore 및 미추적 파일은 checkout에 포함되지 않습니다.

세션 간 테스트가 충돌하면 Git 밖의 DB, 포트, 임시 폴더, 생성기, 공유 캐시를 살펴보세요. 제거가 막히면 해당 worktree에서 git status를 실행하고 필요한 변경을 먼저 보존합니다. 통합을 위해 기본 checkout은 유지하고 등록된 폴더는 worktree 목록으로 확인하세요.