git worktree locked 오류, 이유 확인 후 안전하게 삭제하기

git worktree remove가 cannot remove a locked working tree로 멈추면 이중 --force부터 붙이지 마세요. 먼저 git worktree list --porcelain에서 locked 다음 줄의 이유를 확인합니다. 해당 세션이 끝났거나 잠시 분리한 장치를 다시 연결했고 더는 보호할 필요가 없을 때만 git worktree unlock을 실행한 뒤 일반 remove를 다시 시도하세요.

force 전에 잠금 이유부터 확인하세요

이 작업은 Codex나 Claude 웹사이트가 아니라 Mac의 터미널에서 합니다. Command + Space를 누르고 터미널을 연 뒤, 원본 Git 저장소 경로를 실제 경로로 바꿉니다.

git -C "/원본/저장소" worktree list --porcelain

잠긴 worktree는 다음처럼 경로와 브랜치 아래에 locked가 표시됩니다.

worktree /worktrees/task-a
HEAD 0123456...
branch refs/heads/task-a
locked external drive offline

locked 뒤의 문장은 잠금을 만든 도구나 사람이 남긴 이유입니다. pid 6247처럼 프로세스 번호가 있다면 그 번호가 지금도 실행 중인지 해당 앱의 작업 화면과 함께 확인합니다. 외장 장치나 네트워크 공유를 보호하려고 잠갔다면 먼저 그 경로를 다시 연결합니다.

경로를 잘못 입력해 fatal: not a git repository가 나오면 Finder에서 원본 프로젝트 폴더를 확인하고 다시 실행하세요. linked worktree 폴더 안에서도 조회할 수 있지만, 여러 worktree를 한 번에 볼 때는 원본 저장소에서 실행하는 편이 찾기 쉽습니다.

잠금 목적이 끝났을 때만 해제하세요

Git의 worktree lock은 작업 파일을 암호화하는 기능이 아닙니다. 잠시 보이지 않는 worktree의 관리 정보를 prune이 치우지 못하게 하고, 그 worktree의 move와 remove도 막는 보호 표시입니다.

다음 조건을 확인한 뒤 해제합니다.

1. 잠금 이유에 적힌 앱 세션이나 프로세스가 끝났다.
2. 외장 장치나 네트워크 경로라면 다시 연결되어 파일을 열 수 있다.
3. worktree에서 남길 수정 파일이 없는지 status --short로 확인했다.

git -C "/worktree/경로" status --short
git -C "/원본/저장소" worktree unlock "/worktree/경로"

첫 명령에 M이나 ?? 파일이 나오면 unlock 뒤 바로 삭제하지 마세요. modified or untracked files를 먼저 보존하는 순서로 이동해 커밋·stash·복사 중 하나를 고릅니다.

fatal: '<경로>' is not a working tree가 나오면 worktree list --porcelain에 표시된 정확한 경로를 복사해 다시 실행합니다. 폴더가 이미 사라졌고 목록에 등록만 남았다면 unlock 문제와 다르므로 stale worktree 등록 정리 순서를 확인하세요.

일반 remove와 목록으로 마무리하세요

잠금이 풀리고 파일 상태도 확인했다면 일반 remove를 실행합니다.

git -C "/원본/저장소" worktree remove "/worktree/경로"
git -C "/원본/저장소" worktree list --porcelain

두 번째 목록에서 대상 경로가 사라졌다면 worktree 등록과 폴더 제거가 끝난 것입니다. 브랜치는 별도로 남을 수 있습니다. worktree가 사라졌다고 브랜치까지 자동 삭제된 것은 아닙니다.

실제 재현에서 확인한 결과

2026-09-19에 Git 2.38.1의 비민감 임시 저장소에서 clean linked worktree를 만들고 다음 이유로 잠갔습니다.

git worktree lock --reason "external drive offline" "/worktree/경로"

list --porcelain에는 locked external drive offline이 출력됐습니다. 일반 remove는 exit 128과 함께 멈췄습니다.

fatal: cannot remove a locked working tree, lock reason: external drive offline
use 'remove -f -f' to override or unlock first

git worktree unlock 뒤 같은 일반 remove를 다시 실행하자 성공했고 목록에서 linked 경로가 사라졌습니다. 이 재현은 잠금 이유를 알고 보호 목적이 끝난 clean worktree만 확인한 결과입니다. 살아 있는 앱 작업, 분리된 저장 장치, 수정 파일이 있는 worktree에 강제 제거가 안전하다는 뜻은 아닙니다.

왜 –force를 두 번 붙이지 않나요?

오류 문구는 잠금을 강제로 넘는 방법도 알려 주지만, 잠금 이유가 아직 유효한지는 판단해 주지 않습니다. 다른 앱이 쓰는 중이거나 잠시 오프라인인 worktree라면 강제 제거가 보호 의도를 무시합니다.

따라서 순서는 이유 확인 → 소유 작업 종료 확인 → 파일 상태 확인 → unlock → 일반 remove입니다. 잠금 정보를 만든 도구가 고장 나 unlock 자체가 불가능하고, 파일과 세션을 모두 별도로 확인한 경우에만 강제 제거를 마지막 복구 수단으로 검토하세요.

자주 묻는 질문

unlock하면 파일이 지워지나요?

아닙니다. unlock은 Git의 보호 표시를 풉니다. 실제 폴더와 등록을 지우는 단계는 뒤의 git worktree remove입니다. 다만 unlock 뒤에는 prune·move·remove가 가능해지므로 잠금 목적이 끝났을 때만 실행하세요.

PID가 이유에 적혀 있는데 프로세스가 없으면 바로 지워도 되나요?

프로세스가 없다는 사실만으로 파일이 불필요하다고 단정할 수 없습니다. 해당 앱에서 작업이 종료됐는지 확인하고, worktree 경로의 git status --short와 필요한 파일을 먼저 검사한 뒤 unlock하세요.

검증 기준

• 마지막 업데이트일: 2026-09-19
• 확인 환경: macOS, Git 2.38.1, 비민감 임시 저장소
• 주요 근거: Git git-worktree 공식 문서 · 잠금 이유가 남은 공개 Claude Code 사례
• 확인 범위: clean linked worktree 생성 → reason 포함 lock → 목록 출력 → 일반 remove 거부 → unlock → 일반 remove 성공 → 목록 제거 확인
• 미확인: 정확 월간 검색량, seoin.dev 독자의 직접 피드백, Claude/Codex 앱의 잠금 UI와 버전별 동작
• 공개 이슈는 단일 자기보고이며 제품 전체의 발생 빈도나 공식 원인으로 일반화하지 않는다.
• 대표이미지는 실제 앱 화면이 아닌 잠금 이유 확인→상태 점검→해제를 사물로 표현한 개념도다.
• 대표이미지와 alt, strict SEO100/AEO93, gpt-5.6-sol low 독립 최종검수를 통과했다. 다음 적격일 fresh 발행 게이트는 아직 남았다.

참고: Git 공식 worktree 문서