폴더 이동 후 Git worktree가 안 되나요? repair·prune·remove 전에 양방향 링크 확인

1. 증거를 보존하세요

정리 작업, 가비지 컬렉션, IDE의 워크스페이스 제거,`git worktree prune`을 부르는 스크립트를 중단하세요. 조사 중 어느 디렉터리도 다시 옮기지 마세요.

커밋하지 않거나 추적되지 않는 파일이 있다면 해당 작업 디렉터리 전체를 안전한 위치에 복사하세요. 등록이 깨졌다고 폴더를 버려도 되는 것은 아닙니다.

Git 명령이 아직 작동하는 worktree에서 다음 출력을 저장하세요.

```sh git --version git worktree list --porcelain git worktree prune --dry-run --verbose ```

모의 실행은 진단용입니다. 새 경로에 파일이 남은 worktree를 제거하겠다고 나오면 멈추세요. 오래된 등록의 증거이지 prune 허가가 아닙니다.

각 디렉터리의 절대 경로, 존재 여부와`git status --porcelain=v1` 작동 여부를 기록하세요. 작동하면 상태 출력을, 실패하면 첫 오류를 그대로 저장하세요.

인증 정보, 토큰이 든 원격 URL이나 비공개 파일 내용을 지원 요청에 붙이지 마세요.

2. 양방향 링크 기록표를 만드세요

연결 worktree의 작은`.git` 파일은 주 저장소`.git/worktrees/` 아래의 전용 디렉터리를 가리킵니다. 그 안의`gitdir` 기록은 연결 작업 디렉터리로 돌아갑니다. 따라서 연결은 두 방향입니다.

worktree마다 한 행을 기록하세요.

| 항목 | 기록할 내용 | | --- | --- | | Worktree 이름 | 비밀 프로젝트 이름을 피한 중립적 이름 | | 현재 디렉터리 | 지금 존재하는 경로 | | 목록 디렉터리 | `git worktree list --porcelain`의 경로 | | 연결 측`.git` 대상 | `gitdir:` 대상을 기록하되 편집하지 않음 | | 주 저장소 측`gitdir` 대상 | `.git/worktrees/<id>/gitdir`의 역방향 경로 | | 브랜치 또는 detached HEAD | porcelain 목록이나 저장한 HEAD | | 변경·미추적 상태 | 정확한 상태 요약 또는 상태 확인 불가 | | prune 모의 실행 | 작업 없음 또는 제거 제안 원문 | | 타사 경로 | Git 외부 IDE·워크스페이스 경로 | | 판단 | 주 저장소 이동, 연결 이동, 양쪽 이동, 고아 디렉터리 또는 불명 |

디렉터리 이름만으로 등록을 추측하지 마세요. worktree 이름이 비슷할 수 있으며 관리 디렉터리 이름은 현재 경로를 대신하지 못합니다.

3. repair 전에 이동 유형을 분류하세요

기록표로 다음 중 하나를 선택하세요.

주 worktree만 이동한 경우

연결 worktree의`.git`은 주 저장소의 이전 위치를 가리켜 연결 디렉터리 안의 Git 명령이 실패할 수 있습니다. 새 주 저장소에는 전용 worktree 기록이 남아 있습니다.

새 주 worktree에서 실행하세요.

```sh git worktree repair ```

Git 공식 문서는 이 명령이 연결 worktree와 옮겨진 주 저장소를 다시 연결한다고 설명합니다.

연결 worktree 하나만 이동한 경우

포인터가 주 저장소에 닿아 연결 디렉터리 안에서는 Git 명령이 작동할 수 있습니다. 하지만 주 저장소 측`gitdir`에는 옛 연결 경로가 남고 주 목록에서 이를`prunable`로 표시할 수 있습니다.

옮겨진 연결 worktree 내부에서 실행하세요.

```sh git worktree repair ```

그 뒤 주 worktree의 porcelain 목록이 새 경로를 보여 주는지 확인하세요.

연결 worktree 여러 개를 이동한 경우

주 저장소에 접근할 수 있는 worktree에서 모든 새 연결 경로를 인수로 지정하세요.

```sh git worktree repair /new/path/alpha /new/path/beta ```

진단할 때는 절대 경로를 쓰세요. 상대 링크 정책을 의도적으로 표준화하고 검증한 경우만 예외입니다.

주 worktree와 연결 worktree를 모두 이동한 경우

새 주 worktree에서 각 연결 worktree의 새 경로를 지정하세요.

```sh git worktree repair /new/path/alpha /new/path/beta ```

양쪽을 수동으로 옮긴 뒤 두 방향을 명시적으로 복구하는 유형입니다.

디렉터리는 있지만 등록되지 않은 경우

미등록이라는 말은 삭제해도 된다는 뜻이 아닙니다. 관리 기록이 없어도 커밋하지 않은 작업이 남아 있을 수 있습니다. 보존하고 파일을 검사하며 자동 제거에서 제외하세요. 관계가 불명확하면`repair`가 올바른 관리 기록을 추측해 만들 수 없습니다.

버려도 되는 잔여물인지 확인했더라도 제거는 검사 뒤의 별도 판단입니다. Git 확인 실패만으로 자동 제거하지 마세요.

4. 복구된 연결을 검증하세요

주 worktree와 모든 연결 worktree에서 같은 읽기 전용 검사를 반복하세요.

```sh git worktree list --porcelain git worktree prune --dry-run --verbose git status --porcelain=v1 git rev-parse --path-format=absolute --git-dir git rev-parse --path-format=absolute --git-common-dir ```

다음 조건이 모두 맞을 때만 복구를 인정하세요.

1. 필요한 worktree가 현재 경로로 각각 한 번 나타납니다. 2. 살아 있는 worktree에`prunable` 표시가 없습니다. 3. 각 연결 worktree가 기대한 공통 디렉터리를 찾습니다. 4. 브랜치나 detached HEAD의 정체성이 유지됩니다. 5. 미리 기록한 변경 파일과 미추적 파일이 남아 있습니다. 6. prune 모의 실행이 살아 있는 worktree 제거를 제안하지 않습니다. 7. 타사 워크스페이스·IDE가 맞는 경로를 열거나 별도 미해결 문제로 기록됩니다.

하나라도 실패하면 멈추세요. 증거를 보존하고 강제 옵션으로 넘어가지 마세요.

5. repair·prune·remove·lock을 구분하세요

`git worktree repair`는 오래되거나 손상된 관리 링크를 갱신합니다. 주 worktree나 연결 worktree 이동에 사용하는 일반적인 명령입니다.

`git worktree prune`은 디렉터리가 사라진 worktree의 관리 정보를 제거합니다. 단순히 이동한 디렉터리의 첫 해결책이 아닙니다. 먼저 모의 실행을 확인하세요.

`git worktree remove`는 더 이상 필요 없는 등록 worktree를 제거합니다. Git은 보통 수정·미추적 파일이 있는 worktree를 거부합니다.`--force`는 보호를 약화하며 복구 수단이 아닙니다.

`git worktree lock --reason "..."`은 휴대용 드라이브나 간헐적으로 마운트되는 공유 영역의 worktree를 자동 prune에서 보호합니다. 잘못된 경로는 고치지 않습니다. 잠긴 worktree를 이동·제거하려면 추가 강제 옵션이 필요합니다.

각 명령의 목적은 다릅니다. Git은 주 worktree나 서브모듈을 포함한 연결 worktree의`worktree move`를 지원하지 않고, 상위 프로젝트를 여러 작업 트리로 체크아웃하는 것도 권장하지 않습니다. 이 예시는 그 한계를 해결하지 않습니다. 증거를 보존하고 해당 구성을 따로 조사하세요.

6. 타사 경로 기록은 다른 층으로 다루세요

워크스페이스 제품은 자체 DB에 worktree 절대 경로를 저장할 수 있습니다. 지원되는`git worktree move` 후 Git이 새 경로를 정확히 나열해도 제품은 옛 경로를 열 수 있습니다.

먼저 위 검증으로 Git 상태를 확인하세요. 그다음 제품 문서의 경로 변경, 가져오기 또는 재생성 절차를 검토하세요. 오래된 앱 기록에 맞추려고 Git 관리 정보를 다시 바꾸지 마세요.

타사 결과를 별도로 기록하세요.

- Git 정상, 제품 경로 갱신. - Git 정상, 제품에 경로 변경 기능 없음. - Git 정상, 제품 기록 재생성이 필요하며 앱 상태가 사라질 수 있음. - Git 비정상, 양방향 기록표로 돌아감.

이 경계를 두면 제품의 한계를 Git 복구 실패로 오진하지 않습니다.

7. 임시 저장소 실험에서 확인한 것

임시 Git 2.51.1 저장소에 주 worktree와 연결 worktree 하나를 만들고 연결 디렉터리에 미추적 파일을 넣었습니다.

양쪽을 수동으로 옮기자 주 목록에 이전 연결 경로가`prunable`로 나왔고 prune 모의 실행이 관리 항목 제거를 제안했습니다. 옮긴 연결 디렉터리의`git status`는 실패했습니다. 새 주 위치에서`git worktree repair <new-linked-path>`를 실행하자 양쪽 경로가 복구되고 미추적 파일은 남았습니다.

연결 디렉터리만 옮겼을 때는 내부 status가 작동했지만 주 저장소 쪽 경로는 오래되었습니다. 옮긴 연결 디렉터리 내부의 repair가 주 목록을 갱신했습니다. 주 디렉터리만 옮겼을 때는 연결 포인터가 깨졌고 새 주 위치의 repair가 복구했습니다.

세 가지 임시 Linux 시나리오는 Git 2.51.1에서 실행했습니다. 각 repair 후 변경·미추적 파일의 바이트, HEAD와 브랜치 정체성이 유지됐습니다. 현재 문서는 2.56.0까지 확인했지만 해당 실행 파일은 테스트하지 않았습니다. 모든 Git 릴리스, 네트워크 파일시스템, 서브모듈, IDE나 워크스페이스 DB의 동작을 보장하지 않습니다.

자주 묻는 질문

연결 worktree의.git을 직접 편집해야 하나요?

증거로 보존하되`git worktree repair`를 우선하세요. 한쪽만 편집하면 주 저장소의 역방향 기록이 오래된 채 남을 수 있습니다.

옮긴 연결 폴더에서 git status는 되는데 목록은 왜 옛 경로인가요?

연결 폴더의`.git` 포인터는 주 저장소에 닿지만 주 저장소의`gitdir`은 옛 연결 위치를 가리킬 수 있습니다. 한 방향 복구 유형입니다.

prunable 항목은 안전하게 정리할 수 있나요?

해당 worktree가 정말 사라졌는지 확인하기 전에는 안 됩니다. 살아 있지만 이동한 디렉터리도 이전 경로가 prunable로 보입니다.

repair로 미등록 디렉터리를 복구할 수 있나요?

Git이 연결 관계를 재구성할 관리 정체성 정보가 충분히 남은 경우에만 가능합니다. worktree처럼 보이는 폴더는 유효한 등록의 증거가 아닙니다. 삭제 전에 보존하고 검사하세요.

repair는 IDE나 워크스페이스 관리자도 갱신하나요?

반드시 그렇지는 않습니다. Git은 자신의 관리 정보만 복구합니다. 다른 도구의 별도 절대 경로는 각 도구가 지원하는 갱신·재생성 절차가 필요합니다.