Codex worktree에서 .env가 안 보일 때 커밋 없이 가져오는 법

Local에서는 되는데 Codex worktree에서 환경 변수 오류가 난다면 .env를 Git에 커밋하지 마세요. 먼저 그 파일이 Git에서 무시되는지 확인하고, Codex가 관리하는 새 worktree에만 복사하도록 저장소 루트의 .worktreeinclude에 경로를 적는 것이 핵심입니다.

실제 앱 화면이나 복사 성공 캡처가 아니라, 선택한 ignored 파일만 옮기는 원리를 설명한 개념도입니다.

30초 만에 파일 상태부터 확인하기

Codex에서 연 프로젝트의 Local 폴더로 이동한 뒤 다음 세 명령을 실행합니다.

pwd
git check-ignore -v .env
git ls-files --error-unmatch .env

결과는 이렇게 읽습니다.

결과	뜻	다음 행동
git check-ignore가 .gitignore 규칙을 보여줌	.env는 의도적으로 무시됨	.worktreeinclude 대상으로 검토
git ls-files가 파일 경로를 출력함	이미 Git이 추적하는 파일	비밀값이 들어 있다면 복사 문제가 아니라 보안 점검이 먼저
두 명령 모두 파일을 찾지 못함	무시되지 않은 일반 미추적 파일일 수 있음	파일명·현재 폴더를 다시 확인하고 필요한 설정만 별도로 만들기

git status --ignored --short를 실행하면 무시된 파일은 보통 !! .env처럼 보입니다. 파일 내용은 출력하지 않아도 됩니다.

.worktreeinclude에 필요한 파일만 적기

.gitignore와 같은 저장소 루트에 .worktreeinclude 파일을 만들고 새 worktree에 필요한 ignored 파일만 적습니다. macOS에서는 Command + Space → 터미널 → Enter로 터미널을 연 뒤 저장소 폴더로 이동합니다. 다음 명령은 예시 세 경로만 넣은 새 파일을 만듭니다.

git rev-parse --show-toplevel
cd "$(git rev-parse --show-toplevel)"
printf '%s\n' '.env' '.env.local' 'config/secrets.json' > .worktreeinclude
git status --short .worktreeinclude

마지막 명령에서 ?? .worktreeinclude가 보이면 파일은 만들어졌지만 아직 Git이 추적하지 않는 상태입니다. 팀과 패턴을 공유하려면 실제 비밀 파일이 아니라 .worktreeinclude만 검토해 커밋합니다.

OpenAI 공식 문서에 따르면 Codex가 관리하는 local worktree는 Git checkout에서 시작합니다. 추적 파일은 checkout에 들어오지만, ignored 파일은 .worktreeinclude 패턴과 일치할 때만 복사됩니다. 다른 미추적 파일까지 전부 복사되는 것은 아닙니다.

설정한 뒤에는 Codex 앱에서 새 작업을 시작하고 환경 선택에서 Worktree를 선택해 새 관리형 worktree를 만듭니다. 앱 버전에 따라 선택 항목의 위치나 표현은 달라질 수 있으므로, 화면에 Worktree 선택이 없다면 현재 작업을 Local로 계속한 채 앱 버전과 환경 선택 화면을 확인하세요. 이미 만들어진 worktree에 이 파일을 추가했다고 과거 복사가 자동으로 다시 실행된다고 가정하면 안 됩니다.

새 worktree의 터미널에서 아래 명령으로 성공 여부를 확인합니다. env_file_present가 나오면 파일 복사까지 확인한 것이고, 그다음 원래 실행 명령을 다시 실행해 환경 변수 오류가 사라졌는지 확인합니다. env_file_missing이면 아래 세 가지 조건을 이어서 점검합니다.

test -f .env && echo env_file_present || echo env_file_missing

그래도 안 보일 때 확인할 세 가지

1. .worktreeinclude 위치

파일은 Codex에서 연 프로젝트가 속한 저장소의 루트에 있어야 합니다.

git rev-parse --show-toplevel

출력된 폴더와 .worktreeinclude를 둔 폴더가 같은지 확인합니다. 여러 프로젝트가 들어 있는 저장소라면 현재 연 하위 폴더와 Git 루트를 혼동하기 쉽습니다.

2. 파일이 심볼릭 링크인지

공식 문서는 복사 원본이 심볼릭 링크이면 건너뛴다고 설명합니다.

test -L .env && echo env_is_symlink || echo env_not_symlink_or_missing

env_is_symlink가 나오면 링크입니다. 이 명령은 링크 대상 경로를 출력하지 않습니다. 실제 비밀 저장 위치를 공개하거나 강제로 복사하지 말고, 프로젝트가 요구하는 안전한 로컬 설정 절차를 확인하세요.

3. 테스트 대상이 Codex 관리형 local worktree인지

.worktreeinclude 복사는 ChatGPT 데스크톱 앱이 관리하는 local worktree의 동작입니다. 터미널에서 직접 git worktree add로 만든 폴더나 remote worktree에는 같은 복사를 기대하면 안 됩니다.

직접 재현한 기준선

2026-09-19에 비민감 테스트 저장소를 만들고 .env를 .gitignore에 넣었습니다. source 폴더에서는 파일이 존재했고 git check-ignore도 해당 규칙을 보여줬지만, git worktree add --detach로 만든 raw Git worktree에는 .env가 없었습니다.

source_env_exit=0
worktree_env_exit=1

이 결과는 raw Git checkout의 기준선입니다. Codex 관리형 worktree의 .worktreeinclude 성공을 직접 실행한 화면은 아니므로, 앱 동작에 대한 주장은 공식 문서 범위로 제한합니다.

비밀값을 지키면서 확인하기

• .env 내용을 터미널에 출력하거나 스크린샷에 넣지 않습니다.
• 실제 키를 Git에 커밋하지 않습니다.
• .worktreeinclude에는 프로젝트 실행에 꼭 필요한 ignored 경로만 적습니다.
• 팀 저장소라면 .worktreeinclude에 어떤 경로 패턴을 공유할지 검토하되 실제 비밀 파일은 계속 무시합니다.

.env를 .gitignore에 넣었는데도 이미 Git이 추적하고 있다면 이 글의 복사 절차보다 이미 추적 중인 파일을 안전하게 빼는 순서가 먼저입니다. 새 저장소라 첫 커밋 자체가 없고 invalid reference: HEAD가 함께 보이면 Codex worktree의 HEAD 확인 순서로 질문을 나눠 확인하세요.

막혔을 때 남길 정보

문의할 때는 비밀값 대신 아래 결과만 남깁니다.

git rev-parse --show-toplevel
git check-ignore -v .env
git ls-files --error-unmatch .env
test -f .worktreeinclude && echo include_file_present || echo include_file_missing
test -L .env && echo env_is_symlink || echo env_not_symlink_or_missing

여기에 Codex 앱 버전, 새 worktree를 만든 시각, local인지 worktree인지도 적으면 “파일이 없는 문제”와 “환경 변수가 읽히지 않는 문제”를 나누기 쉽습니다. 사용자명이나 저장소명이 포함된 경로는 공유 전에 가립니다.

자주 묻는 질문

.worktreeinclude를 Git에 커밋해도 되나요?

경로 패턴만 적고 실제 비밀값은 넣지 않는다면 팀이 같은 로컬 파일 구조를 준비하는 데 쓸 수 있습니다. 다만 팀원이 모두 같은 파일을 필요로 하는지 먼저 확인하고, .env 자체는 계속 .gitignore로 제외합니다.

기존 worktree에도 파일이 바로 생기나요?

그렇게 가정하지 마세요. .worktreeinclude는 Codex가 새 local worktree를 만들 때 복사할 ignored 파일을 정하는 용도입니다. 설정 뒤 새 worktree에서 확인하고, 기존 worktree에는 비밀 관리 절차에 따라 별도로 준비합니다.

raw Git worktree에도 같은 기능이 적용되나요?

아닙니다. 터미널의 git worktree add는 Git checkout을 만들 뿐 Codex의 .worktreeinclude 복사 단계를 실행하지 않습니다. 이번 직접 재현에서도 ignored .env는 raw Git worktree에 나타나지 않았습니다.

검증 기준

• 마지막 업데이트일: 2026-09-19
• 확인 환경: macOS, Git 2.38.1, 비민감 임시 저장소와 raw detached worktree
• 직접 확인: source의 ignored .env 존재, git check-ignore 규칙, raw Git worktree의 .env 부재
• 직접 확인하지 않음: Codex App 관리형 local worktree에서 .worktreeinclude가 파일을 복사하는 실제 화면, remote worktree 동작
• 주요 근거: OpenAI 공식 Codex worktree 문서
• 2026-09-19 KST Google·Naver 실제 검색 결과에서 정확 질문과 일반 worktree 답을 대조했습니다. 검색 순위는 검색량이 아닙니다.
• 비민감 raw Git worktree에서 ignored .env가 따라오지 않는 것을 직접 재현했습니다.
• Codex 관리형 local worktree의 .worktreeinclude, symlink 건너뛰기, 기존 파일 비덮어쓰기, remote/raw Git 제외 조건은 2026-09-19 확인한 공식 OpenAI 문서에 근거합니다.
• 대표 이미지는 개념도이며 실제 앱 화면이나 복사 성공의 증거가 아닙니다.

참고: OpenAI 공식 Codex worktree 문서