작업 트리

Source URL: https://developers.openai.com/codex/app/worktrees

작업 트리

Codex 앱에서 작업 트리를 사용하면 같은 프로젝트 내에서 서로 간섭 없이 여러 개의 독립적인 작업을 실행할 수 있습니다. Git 저장소의 경우 자동화는 지속적으로 진행 중인 작업과 충돌하지 않도록 전용 백그라운드 작업 트리에서 실행됩니다. 버전 관리되지 않은 프로젝트에서는 자동화가 프로젝트 디렉토리에서 직접 실행됩니다. 작업 트리에서 수동으로 스레드를 시작할 수도 있습니다.

작업 트리란

작업 트리는 Git 작업 트리를 기반으로 하기 때문에 Git 저장소에 해당하는 프로젝트에서만 작동합니다. 작업 트리는 저장소의 두 번째 복사본(“체크아웃”)을 생성할 수 있게 해줍니다. 각 작업 트리는 저장소의 모든 파일을 자체적으로 갖고 있지만 커밋, 브랜치 등에 관한 동일한 메타데이터(.git 폴더)를 공유합니다. 이 덕분에 여러 브랜치를 병렬로 체크아웃하고 작업할 수 있습니다.

용어 정리

• 로컬 체크아웃: 당신이 만든 저장소입니다. Codex 앱에서는 때때로 단순히 로컬이라고도 합니다.
• 작업 트리: Codex 앱에서 로컬 체크아웃을 기반으로 생성한 Git 작업 트리입니다.

작업 트리를 사용하는 이유

1. Codex와 함께 작업하면서 서로의 진행을 방해하지 않고 병렬로 작업할 수 있습니다.
2. 현재 작업과 관계없는 스레드를 시작합니다.
   • 아직 테스트할 준비가 되지 않은 작업을 Codex에 시작하도록 대기열에 올려두는 스테이징 영역입니다.

시작하기

작업 트리를 사용하려면 Git 저장소가 필요합니다. 선택한 프로젝트가 Git 저장소에 속해 있는지 확인하세요.

1. “작업 트리(Worktree)” 선택

   새 스레드 보기에서 컴포저 아래의 작업 트리를 선택합니다. 선택적으로, 작업 트리 설정 스크립트를 실행할 로컬 환경을 지정할 수 있습니다.

2. 시작 브랜치 선택

   컴포저 아래에서 작업 트리를 기반으로 할 Git 브랜치를 선택합니다. main/master 브랜치, 기능 브랜치, 또는 현재 변경 사항이 있는 브랜치가 될 수 있습니다.

3. 프롬프트 제출

   작업을 제출하면 Codex가 선택한 브랜치를 바탕으로 Git 작업 트리를 생성합니다. 기본적으로 Codex는 “detached HEAD” 상태로 작업합니다.

4. 변경 내용 검증

   준비되면 프로젝트와 작업 흐름에 따라 아래의 경로 중 하나를 따르세요.

작업 흐름 변경 사항 검증 및 푸시

작업 트리는 로컬 체크아웃과 모습이나 느낌이 비슷합니다. 그러나 Git은 브랜치를 동시에 여러 장소에서 체크아웃할 수 없도록 합니다. 작업 트리에서 브랜치를 체크아웃하면 로컬 체크아웃에서는 동시에 체크아웃할 수 없으며, 반대도 마찬가지입니다.

따라서 작업 트리에서 Codex가 만든 변경 사항을 어떻게 검증하고 커밋할지 선택해야 합니다.

1. 작업 트리에서만 작업. 이 방식은 로컬 환경 설정 스크립트를 통해 종속성이나 도구를 설치하여 작업 트리에서 직접 변경 사항을 검증할 수 있을 때 가장 잘 작동합니다.
2. 로컬 체크아웃에서 작업. 애플리케이션을 한 인스턴스만 실행할 수 있어서 변경 사항을 메인 체크아웃으로 가져와야 할 경우에 사용하세요.

옵션 1: 작업 트리에서 작업하기

작업 트리에서 변경 사항을 계속 유지하고 싶으면 스레드 헤더의 여기에 브랜치 생성(Create branch here) 버튼을 눌러 작업 트리를 브랜치로 전환하세요.

여기서 변경 사항을 커밋하고 브랜치를 원격 저장소로 푸시하며 GitHub에서 PR을 열 수 있습니다.

헤더의 “열기(Open)” 버튼을 눌러 작업 트리를 IDE에서 열거나 통합 터미널을 사용하거나 작업 트리 디렉토리에서 필요한 모든 작업을 수행할 수 있습니다.

작업 트리에 브랜치를 생성하면 해당 브랜치는 로컬 체크아웃을 포함한 다른 작업 트리에서 체크아웃할 수 없습니다.

이 브랜치에서 계속 작업할 계획이라면 사이드바에 추가하세요. 그렇지 않다면 작업이 끝난 후 스레드를 보관하여 작업 트리를 삭제할 수 있도록 하세요.

옵션 2: 로컬 체크아웃에서 작업하기

작업 트리에서 직접 변경 내용을 검증하지 않고 로컬 체크아웃에서 체크아웃하려면 스레드 헤더에서 **로컬과 동기화(Sync with local)**를 클릭하세요.

새 브랜치를 생성하거나 기존 브랜치에 동기화할지를 선택할 수 있습니다.

동기화는 언제든지 할 수 있습니다. 다시 헤더의 로컬과 동기화를 클릭하면 동기화 방향(로컬으로 또는 로컬에서)과 동기화 방법을 선택할 수 있습니다:

• 덮어쓰기(Overwrite): 대상 체크아웃이 원본 체크아웃의 파일 및 커밋 이력을 일치시킵니다.
• 적용(Apply): 가장 가까운 공통 커밋 이후의 원본 변경 사항을 계산하여 패치를 대상 체크아웃에 적용합니다. 이 방식은 대상의 커밋 이력을 유지하면서 원본 코드 변경 사항만 가져옵니다(원본 커밋은 가져오지 않음).

여러 작업 트리를 생성하고 동일한 기능 브랜치에 동기화하여 작업을 병렬 스레드로 분할할 수 있습니다.

어떤 경우에는 작업 트리의 변경 사항이 이전 작업 트리에서 테스트한 로컬 체크아웃의 변경과 충돌할 수 있습니다. 이럴 때는 로컬 덮어쓰기(Overwrite local) 옵션을 사용하여 이전 변경 사항을 초기화하고 작업 트리의 변경만 적용할 수 있습니다.

이 과정은 Git 작업을 사용하므로 .gitignore에 포함된 파일은 동기화 과정에서 이전되지 않습니다.

작업 트리를 사이드바에 추가하기

위의 옵션 1(작업 트리에서 작업)을 선택하면 작업 트리에 브랜치를 생성한 후 헤더에 사이드바에 작업 트리를 추가할 수 있는 옵션이 나타납니다. 이 작업을 하면 작업 트리가 영구적인 위치로 승격되어 자동으로 삭제되지 않으며 동일한 작업 트리에서 새 스레드를 시작할 수도 있습니다.

고급 상세 정보

Codex가 작업 트리를 관리하는 방식

Codex는 $CODEX_HOME/worktrees에 작업 트리를 생성합니다. 시작 커밋은 스레드를 시작할 때 선택한 브랜치의 HEAD 커밋입니다. 로컬 변경 사항이 있는 브랜치를 선택하면 커밋되지 않은 변경 사항도 작업 트리에 적용됩니다. 작업 트리는 브랜치로 체크아웃되지 않고 detached HEAD 상태로 유지됩니다. 이는 브랜치를 오염시키지 않고 여러 작업 트리를 생성할 수 있게 해줍니다.

브랜치 제한 사항

Codex가 작업 트리에서 작업을 마치고 여기에 브랜치 생성을 통해 feature/a 브랜치를 만들었다고 가정해 봅시다. 이제 로컬 체크아웃에서 사용하려고 합니다. 브랜치를 체크아웃하려 하면 다음과 같은 오류가 발생합니다:

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

이 문제를 해결하려면 작업 트리에서 feature/a 대신 다른 브랜치를 체크아웃해야 합니다.

로컬에서 브랜치를 체크아웃할 계획이라면 워크플로 2(로컬과 동기화)를 사용해 보세요.

왜 이러한 제한이 있는가

Git은 브랜치가 작업 트리당 한 곳에서만 체크아웃되도록 제한합니다. 브랜치는 변경 가능한 단일 참조(refs/heads/<name>)로, 해당 작업 트리에서 현재 체크아웃된 상태를 나타냅니다.

브랜치를 체크아웃하면 Git은 해당 브랜치의 HEAD가 그 작업 트리에 속한 것으로 간주하며 커밋, 리셋, 리베이스, 병합 등의 작업이 그 참조를 명확하고 직렬화된 방식으로 진행하도록 기대합니다. 동일한 브랜치를 여러 작업 트리에서 동시에 체크아웃하면 어떤 작업 트리의 작업이 브랜치 참조를 업데이트하는지에 대한 모호성과 경쟁 상태가 발생하여 커밋 누락, 일관성 없는 인덱스, 해결되지 않은 충돌 등이 생길 수 있습니다.

따라서 Git은 브랜치마다 하나의 권한 있는 작업 복사본만 유지하도록 보장하면서도 다른 작업 트리에서 detached HEAD나 별도의 브랜치를 통해 동일한 커밋을 안전하게 참조할 수 있게 합니다.

작업 트리 정리

작업 트리는 많은 디스크 공간을 차지할 수 있습니다. 각 작업 트리는 자체 저장소 파일, 종속성, 빌드 캐시 등을 갖고 있습니다. 따라서 Codex 앱은 작업 트리 수를 적절한 수준으로 유지하려고 합니다.

작업 트리는 다음 조건이 있으면 절대 정리되지 않습니다:

• 고정된 대화(pinned conversation)가 연결된 작업 트리
• 사이드바에 추가된 작업 트리(위 참조)

다음 조건이 충족될 때 작업 트리는 정리 대상이 됩니다:

• 생성된 지 4일이 넘은 경우
• 작업 트리가 10개를 초과한 경우

이러한 조건 중 하나라도 만족되면 스레드를 보관하거나 앱을 시작할 때 연결된 스레드가 없는 작업 트리를 자동으로 정리합니다.

작업 트리를 정리하기 전에 Codex는 언제든지 새 작업 트리로 복원할 수 있는 스냅샷을 저장합니다. 작업 트리를 정리한 후 대화를 다시 열면 해당 작업 트리를 복원할 수 있는 옵션이 표시됩니다.

자주 묻는 질문

작업 트리를 생성할 위치를 제어할 수 있나요?

현재는 불가능합니다. Codex는 $CODEX_HOME/worktrees에 작업 트리를 생성하여 일관되게 관리합니다.

세션을 작업 트리 간에 이동할 수 있나요?

아직은 아닙니다. 환경을 바꿔야 한다면 대상 환경에서 새 스레드를 시작하고 프롬프트를 다시 작성해야 합니다. 컴포저에서 위쪽 화살표 키를 사용해 프롬프트를 되살릴 수 있습니다.

작업 트리가 삭제되면 스레드는 어떻게 되나요?

작업 트리 디렉토리가 정리되어도 스레드는 기록(history)에 남을 수 있습니다. 그러나 Codex는 정리 전에 작업 트리의 스냅샷을 저장하고 관련된 스레드를 다시 열면 복원 옵션을 제공합니다.