Git worktree에서 .venv·ruff가 없다고 할 때 확인 순서

메타디스크립션: Git worktree에서 .venv와 ruff가 없을 때 현재 경로를 확인하고, worktree별 새 가상환경과 검증한 공유 경로 중 하나를 고르는 순서를 설명한다.

Git worktree에서 ruff is not installed가 나오는데 기본 프로젝트 폴더에서는 잘 된다면, 먼저 재설치 실패가 아니라 가상환경 경로가 새 worktree에 없는 상황인지 확인하세요. .venv는 보통 .gitignore에 들어가므로 새 worktree에 자동 복제되지 않습니다.

1분 확인

worktree 터미널에서 다음 두 줄을 실행합니다.

pwd
test -x .venv/bin/ruff && echo "worktree ruff 있음" || echo "worktree ruff 없음"

없음이 나오면 ruff 자체가 고장났다고 단정하지 말고 아래 두 방법 중 하나를 고릅니다. 이 명령과 재현은 macOS에서 확인했으며, Windows의 venv 경로와 PowerShell 명령은 이번 검증 범위에 들지 않습니다.

방법 1: worktree마다 새 가상환경 만들기

의존성이나 Python 버전이 달라질 수 있다면 이 방법이 가장 단순합니다.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m ruff check .

설치 파일이 pyproject.toml, requirements-dev.txt, uv.lock 등이라면 프로젝트가 이미 쓰는 설치 명령을 그대로 사용하세요. 임의로 다른 의존성 파일을 만들지는 않습니다.

완료 여부는 활성화 프롬프트가 아니라 다음 출력으로 확인합니다.

.venv/bin/python -m pip --version
.venv/bin/python -m ruff --version
git status --short

.venv가 무시돼 있다면 git status --short에 환경 파일 수천 개가 나타나지 않아야 합니다.

새 worktree 자체의 환경 스크립트가 실행되지 않은 상황이라면 Codex worktree에서 환경 Run이 없을 때 확인할 것에서 setup 스크립트와 지금의 Python 경로를 따로 점검하세요.

방법 2: 기본 checkout의 환경을 명시적으로 사용하기

두 worktree가 같은 Python과 같은 의존성을 쓰고, 설치 속도를 줄이는 것이 더 중요하다면 수동 명령에서 기존 실행 파일의 검증한 절대경로를 사용할 수 있습니다.

먼저 작업 폴더를 추측하지 말고 등록된 worktree를 봅니다.

git worktree list --porcelain

출력의 worktree /경로 중 기본 checkout을 확인한 뒤 그 환경이 실제로 실행되는지 검사합니다.

/확인한/기본-checkout/.venv/bin/python -m ruff --version
/확인한/기본-checkout/.venv/bin/python -m ruff check .

저장소마다 기본 checkout 위치가 다르므로 위 예시 경로를 그대로 복사하면 안 됩니다. hook이 <현재 worktree>/.venv만 찾도록 고정돼 있다면 이 글에서 검증하지 않은 설정 문법을 추측해 바꾸지 마세요. 방법 1로 현재 worktree에 환경을 만들거나, 해당 hook의 공식 설정에서 외부 실행 파일 경로를 받는지 별도로 확인해야 합니다.

여기서 git worktree list --porcelain이 알 수 없는 경로를 보이거나 등록과 실제 폴더가 다르면 가상환경을 만들기 전에 stale worktree 등록을 정리하는 순서로 경로 상태부터 확인하세요.

언제 공유하면 안 되나요?

브랜치별 Python·의존성·실행 조건이 다르거나 두 작업이 같은 환경을 바꿀 수 있다면 공유하지 않습니다.

다음 중 하나라도 해당하면 worktree별 환경을 만드세요.

• 브랜치마다 requirements.txt, lock 파일, Python 버전이 다르다.
• native extension을 빌드하거나 OS·아키텍처가 다르다.
• 두 작업이 동시에 패키지를 설치·업데이트한다.
• 테스트가 환경 내부 파일을 쓰고 서로 영향을 줄 수 있다.

공유 venv는 설치 시간을 줄이지만 작업 격리를 약하게 만듭니다. 한 worktree에서 패키지를 설치·업데이트하면 다른 worktree의 다음 실행 결과도 즉시 바뀌 수 있습니다. “같은 저장소”만으로 공유 조건이 충족되는 것은 아닙니다.

직접 재현한 결과

Git 2.38.1의 비민감 fixture에서 기본 checkout에만 .venv/bin/ruff를 만들고 같은 commit으로 linked worktree를 추가했습니다. 기본 실행 파일은 동작했지만 새 worktree의 .venv/bin/ruff는 missing이었고, worktree의 git status --short는 깨끗했습니다.

즉, Git 오류가 아니라 추적하지 않는 로컬 가상환경이 별도 작업 폴더로 복제되지 않은 정상적인 경로 차이였습니다. 공개 질문의 특정 Claude hook 버그를 그대로 재현한 것은 아니며, Git 경로 조건만 독립 확인했습니다.

정리

1. 현재 worktree에 .venv 실행 파일이 있는지 먼저 확인합니다.
2. 브랜치별 의존성이 다르면 worktree마다 새 venv를 만듭니다.
3. 완전히 같은 환경을 의도했다면 git worktree list --porcelain로 기본 checkout을 확인하고 검증한 절대경로를 사용합니다.
4. python -m ruff --version과 실제 검사 결과로 해결 여부를 확인합니다.

자주 묻는 질문

기본 checkout의 .venv를 새 worktree에 복사해도 되나요?

복사보다 새 worktree에서 프로젝트가 지정한 설치 명령을 실행하는 편이 안전합니다. 가상환경 안의 절대경로와 native extension은 폴더를 복사했다고 동일한 조건을 보장하지 않습니다.

.venv가 없으면 Git worktree 오류인가요?

아닙니다. .venv가 Git에서 무시된 로컬 폴더라면 새 worktree에 없는 것이 정상일 수 있습니다. 현재 경로에서 실행 파일을 확인한 뒤, 독립 환경을 만들지 검증한 기존 환경을 명시할지 고릅니다.

검증 기준

• 마지막 업데이트일: 2026-09-23
• 확인 환경: macOS, Git 2.38.1의 비민감 임시 저장소
• 주요 근거: Git worktree 공식 문서, 공개 실패 사례
• 직접 확인: 같은 commit의 기본 checkout에서만 무시된 .venv/bin/ruff fixture가 실행됐고, linked worktree에서는 missing이었다.
• 한계: 실제 Claude Code hook, Windows venv 생성, ruff 패키지 설치는 이번 검증에 포함하지 않았다.

검증 범위: 2026-09-23 macOS Git 2.38.1의 로컬 fixture. 실제 Claude Code 계정·hook 실행, Windows venv 생성, ruff 패키지 설치는 이번 회차에 실행하지 않았다.