Worktree
Worktree
ChatGPT 데스크톱 앱의 Codex에서 Git worktree를 사용하여 채팅을 병렬로 실행하세요
작업 트리를 사용하면 Codex가 같은 프로젝트에서 서로 간섭하지 않는 여러 독립적인 채팅을 실행할 수 있습니다. 저장소, 작업 트리 및 명령은 프로젝트가 있는 컴퓨터나 원격 개발 환경에 그대로 유지됩니다. ChatGPT 데스크톱 앱에서 직접 작업하거나, ChatGPT 모바일 앱에서 Remote를 사용하여 연결된 컴퓨터의 작업 트리 채팅을 시작하고, 안내하고, 승인하고, 검토할 수 있습니다.
Git 저장소에서는 예약된 작업을 전용 백그라운드 작업 트리에서 실행하여 진행 중인 작업과 충돌하지 않도록 할 수 있습니다. 버전 관리가 적용되지 않는 프로젝트에서는 예약된 작업이 프로젝트 디렉터리에서 직접 실행됩니다. 작업 트리에서 채팅을 수동으로 시작하고 Handoff를 사용하여 채팅을 Local과 Worktree 간에 이동할 수도 있습니다.
Worktree란?
Worktree는 내부적으로 Git worktree를 사용하므로 Git 저장소에 속한 프로젝트에서만 작동합니다. Worktree를 사용하면 저장소의 두 번째 사본("checkout")을 만들 수 있습니다. 각 worktree에는 저장소의 모든 파일이 별도로 복사되지만, 커밋과 브랜치 등에 관한 메타데이터(.git 폴더)는 모두 공유합니다. 따라서 여러 브랜치를 동시에 checkout하고 작업할 수 있습니다.
용어
- Local checkout: 사용자가 만든 저장소입니다. ChatGPT 데스크톱 앱에서는 간단히 Local이라고도 합니다.
- Worktree: ChatGPT 데스크톱 앱에서 local checkout으로부터 생성한 Git worktree입니다.
- Handoff: Local과 Worktree 간에 채팅을 이동하는 흐름입니다. Codex가 두 환경 사이에서 작업을 안전하게 이동하는 데 필요한 Git 작업을 처리합니다.
Worktree를 사용하는 이유
- 현재 Local 설정을 방해하지 않고 Codex와 병렬로 작업할 수 있습니다.
- 포그라운드 작업에 집중하면서 백그라운드 작업을 대기열에 추가할 수 있습니다.
- 변경 사항을 검사하거나 테스트하거나 더 직접적으로 협업할 준비가 되면 나중에 채팅을 Local로 옮길 수 있습니다.
시작하기
Worktree를 사용하려면 Git 저장소가 필요합니다. 선택한 프로젝트가 Git 저장소에 있는지 확인하세요.
"Worktree" 선택
새 채팅 보기의 작성기 아래에서 Worktree를 선택합니다. 선택적으로 worktree의 설정 스크립트를 실행할 로컬 환경을 선택합니다.
시작 브랜치 선택
작성기 아래에서 worktree의 기반으로 사용할 Git 브랜치를 선택합니다.
main/master브랜치, 기능 브랜치 또는 스테이징되지 않은 로컬 변경 사항이 있는 현재 브랜치를 선택할 수 있습니다.프롬프트 제출
프롬프트를 제출하면 Codex가 선택한 브랜치를 기반으로 Git worktree를 생성합니다. 기본적으로 Codex는 "detached HEAD"에서 작업합니다.
작업을 계속할 위치 선택
준비가 되면 worktree에서 바로 계속 작업하거나 채팅을 local checkout으로 Handoff할 수 있습니다. Local로 또는 Local에서 Handoff하면 채팅과 코드를 모두 이동하여 다른 checkout에서 계속 작업할 수 있습니다.
Local과 Worktree 간에 작업하기
Worktree의 모양과 사용 방식은 local checkout과 매우 비슷합니다. 차이점은 워크플로에서의 역할입니다. Local을 포그라운드, Worktree를 백그라운드라고 생각하면 됩니다. Handoff를 사용하면 두 환경 간에 채팅을 이동할 수 있습니다.
내부적으로 Handoff는 두 checkout 사이에서 작업을 안전하게 이동하는 데 필요한 Git 작업을 처리합니다. 이는 Git에서는 브랜치를 한 번에 한 위치에서만 checkout할 수 있기 때문에 중요합니다. Worktree에서 브랜치를 checkout하면 local checkout에서는 동시에 해당 브랜치를 checkout할 수 없으며, 그 반대도 마찬가지입니다.
실제로는 다음 두 가지 경로가 일반적입니다.
- Worktree에서만 작업합니다. 예를 들어 로컬 환경 설정 스크립트를 사용해 종속 요소와 도구를 설치하여 worktree에서 변경 사항을 직접 확인할 수 있을 때 가장 적합합니다.
- 채팅을 Local로 Handoff합니다. 일반적으로 사용하는 IDE에서 변경 사항을 검사하고 싶거나 앱 인스턴스를 하나만 실행할 수 있는 경우처럼 채팅을 포그라운드로 가져오려면 이 경로를 사용하세요.
옵션 1: Worktree에서 작업하기
변경 사항과 함께 worktree에서만 계속 작업하려면 채팅 헤더의 Create branch here 버튼을 사용하여 worktree를 브랜치로 전환하세요.
그런 다음 변경 사항을 커밋하고 브랜치를 원격 저장소로 push한 후 GitHub에서 pull request를 열 수 있습니다.
헤더의 "Open" 버튼을 사용하여 작업 트리를 IDE에서 열거나, 통합 터미널을 사용하거나, 작업 트리 디렉터리에서 필요한 다른 작업을 수행할 수 있습니다.
옵션 2: 채팅을 Local로 Handoff하기
채팅을 포그라운드로 가져오려면 채팅 헤더에서 Hand off를 선택하고 Local로 이동하세요.
평소 사용하는 IDE 창에서 변경 사항을 확인하거나, 기존 개발 서버를 실행하거나, 일상적으로 사용하는 동일한 환경에서 작업을 검증하려는 경우에 적합한 경로입니다.
Codex는 worktree와 local checkout 사이에서 채팅을 안전하게 이동하는 데 필요한 Git 단계를 처리합니다.
각 채팅은 시간이 지나도 동일한 작업 트리와 연결된 상태를 유지합니다. 나중에 채팅을 다시 작업 트리로 넘기면 Codex는 중단한 지점부터 이어서 작업할 수 있도록 동일한 백그라운드 환경으로 채팅을 되돌립니다.
Handoff는 Git 작업을 사용하므로 .gitignore 파일의 일부인 파일은 Codex가 .worktreeinclude를 사용하여 로컬 관리형 worktree로 복사하지 않는 한 채팅과 함께 이동하지 않습니다.
고급 세부 정보
Codex 관리형 및 영구 worktree
기본적으로 채팅은 Codex 관리형 worktree를 사용합니다. 이러한 worktree는 가볍고 일회용으로 사용할 수 있도록 설계되었습니다. Codex 관리형 worktree는 일반적으로 하나의 채팅 전용이며, 나중에 해당 채팅을 다시 worktree로 Handoff하면 Codex가 동일한 worktree로 돌려보냅니다.
장기간 사용할 환경이 필요하다면 사이드바에서 프로젝트의 점 세 개 메뉴를 통해 영구 worktree를 만드세요. 그러면 새로운 영구 worktree가 별도 프로젝트로 생성됩니다. 영구 worktree는 자동으로 삭제되지 않으며 동일한 worktree에서 여러 채팅을 시작할 수 있습니다.
Codex가 worktree를 관리하는 방식
Codex는 $CODEX_HOME/worktrees에 작업 트리를 생성합니다. 시작 커밋은 채팅을 시작할 때 선택한 브랜치의 HEAD 커밋입니다. 로컬 변경 사항이 있는 브랜치를 선택한 경우 Codex는 커밋되지 않은 변경 사항도 작업 트리에 적용합니다. 작업 트리는 브랜치로 체크아웃되지 않으며 detached HEAD 상태입니다. 따라서 Codex는 브랜치를 어지럽히지 않고 여러 작업 트리를 생성할 수 있습니다.
무시된 로컬 파일을 관리형 worktree로 복사하기
로컬 Codex 관리형 worktree는 Git checkout에서 시작하므로 추적되는 파일은 이미 존재합니다. 저장소에서 새 worktree에 필요한 로컬 설정 파일을 무시하고 있다면 저장소 루트에 .worktreeinclude 파일을 추가하고, Codex가 관리형 worktree를 생성할 때 복사할 무시된 경로나 .gitignore 스타일 패턴을 나열하세요.
.env, .env.local 또는 config/secrets.json처럼 Git이 의도적으로 무시하는 파일에 사용하세요. Codex는 .worktreeinclude와 일치하는 무시된 파일만 복사하며 Git이 추적하지 않는 다른 로컬 파일은 복사하지 않습니다. 추적되는 파일은 나열하지 마세요.
Codex는 무시된 AGENTS.override.md를 로컬 관리형 worktree로 자동 복사하므로 .worktreeinclude에 나열할 필요가 없습니다.
# .worktreeinclude
.env
.env.local
config/secrets.jsonCodex는 소스 심볼릭 링크를 건너뛰고 새 checkout에 이미 있는 파일을 덮어쓰지 않습니다. 이 동작은 로컬 ChatGPT 데스크톱 앱 관리형 worktree에 적용되며, 원격 worktree나 명령줄에서 직접 생성한 Git worktree에는 적용되지 않습니다.
브랜치 제한 사항
Codex가 worktree에서 작업을 완료한 후 Create branch here를 사용하여 해당 위치에 feature/a 브랜치를 생성했다고 가정해 보겠습니다. 이제 local checkout에서 이를 사용하려고 합니다. 브랜치를 checkout하려고 하면 다음 오류가 발생합니다.
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'이 문제를 해결하려면 worktree에서 feature/a 대신 다른 브랜치를 checkout해야 합니다.
브랜치를 로컬에서 checkout할 계획이라면 두 위치에서 동일한 브랜치를 동시에 checkout하려 하지 말고 Handoff를 사용하여 채팅을 Local로 이동하세요.
이 제한이 존재하는 이유
브랜치는 작업 트리의 “현재 체크아웃된 상태”를 의미하는 변경 가능한 단일 참조(`refs/heads/브랜치를 checkout하면 Git은 해당 브랜치의 HEAD가 그 worktree에 속한 것으로 간주하며, 커밋, 재설정, rebase, merge 같은 작업이 잘 정의된 순차적 방식으로 해당 참조를 진행시킬 것으로 예상합니다. 여러 worktree에서 동일한 브랜치를 동시에 checkout하도록 허용하면 어느 worktree의 작업이 브랜치 참조를 업데이트하는지에 관해 모호성과 경쟁 상태가 발생하여 커밋 손실, 일관되지 않은 인덱스 또는 불분명한 충돌 해결로 이어질 수 있습니다.
Git은 worktree당 하나의 브랜치만 허용하여 각 브랜치에 하나의 권위 있는 작업 사본이 있도록 보장하는 동시에, 다른 worktree에서는 detached HEAD나 별도 브랜치를 통해 같은 커밋을 안전하게 참조할 수 있게 합니다.
Worktree 정리
Worktree는 디스크 공간을 많이 차지할 수 있습니다. 각각에 고유한 저장소 파일, 종속 요소, 빌드 캐시 등이 있기 때문입니다. 따라서 ChatGPT 데스크톱 앱은 worktree 수를 적절한 한도 내로 유지하려고 합니다.
기본적으로 Codex는 가장 최근의 Codex 관리형 worktree 15개를 유지합니다. 디스크 사용량을 직접 관리하려면 설정에서 이 한도를 변경하거나 자동 삭제를 끌 수 있습니다.
Codex는 여전히 중요한 worktree를 삭제하지 않으려고 합니다. 다음의 경우 Codex 관리형 worktree는 자동으로 삭제되지 않습니다.
- 고정된 채팅이 연결되어 있음
- 채팅이 아직 진행 중임
- 영구 worktree임
다음의 경우 Codex 관리형 worktree가 자동으로 삭제됩니다.
- 연결된 채팅을 보관 처리함
- 구성된 한도를 유지하기 위해 Codex가 오래된 worktree를 삭제해야 함
Codex는 관리형 worktree를 삭제하기 전에 해당 worktree의 작업 스냅샷을 저장합니다. Worktree가 삭제된 후 채팅을 열면 이를 복원하는 옵션이 표시됩니다.