git worktree rename, 폴더 이름은 `move`로 어떻게 바꾸나?

git worktree rename이라는 별도 명령은 없다. 연결된 Git worktree의 폴더 이름을 바꾸려면 일반 mv보다 git worktree move를 먼저 사용한다. 이 명령은 폴더와 Git의 등록 경로를 함께 바꾼다. 실행 전 작업 상태를 확인하고, 실행 뒤 브랜치·수정 파일·새 경로가 모두 유지됐는지 검증한다.

git -C "/원본/저장소" worktree list --porcelain
git -C "/기존/worktree/경로" status --short
git -C "/원본/저장소" worktree move "/기존/worktree/경로" "/새/worktree/경로"

이동 전에 무엇을 확인해야 하나?

먼저 목록에서 바꾸려는 경로가 main working tree가 아닌 linked worktree인지 확인한다. 이어서 상태를 본다.

git -C "/기존/worktree/경로" status --short

M은 수정된 추적 파일, ??는 아직 추적하지 않은 파일이다. 이 글의 Git 2.38.1 재현에서는 두 종류 파일이 있는 상태에서도 move가 성공하고 파일이 유지됐다. 그래도 중요한 파일은 별도 복사본이나 커밋·stash 등 자신에게 맞는 보존 수단을 먼저 정한다.

폴더 이름은 어떤 명령으로 바꾸나?

원본 저장소에서 기존 경로와 새 경로를 모두 명시한다.

git -C "/원본/저장소" worktree move \
  "/기존/worktree/경로" \
  "/새/worktree/경로"

새 경로가 이미 존재하거나 부모 폴더에 쓸 권한이 없으면 여기서 멈추고 경로를 다시 고른다. --force부터 붙여 기존 폴더를 덮는 절차로 사용하지 않는다.

이동 뒤 무엇이 유지됐는지 확인하나?

git -C "/새/worktree/경로" branch --show-current
git -C "/새/worktree/경로" status --short
git -C "/원본/저장소" worktree list --porcelain

직접 재현에서는 old-name 경로를 new-name으로 옮긴 뒤에도 브랜치는 feature였다. 이동 전의 M tracked.txt와 ?? notes.txt도 그대로 표시됐고, notes.txt 내용도 유지됐다. 목록에는 이전 경로 대신 새 경로가 기록됐다.

move를 쓰면 안 되는 경우는 무엇인가?

Git 공식 문서는 main working tree와 submodule이 든 linked worktree를 worktree move로 옮길 수 없다고 설명한다. main working tree를 수동으로 옮겼다면 stale worktree 등록과 repair를 구분하는 순서가 필요하다. submodule이 든 경우는 submodule worktree 이동 제한과 대체 절차처럼 별도 clone·검증이 필요한 문제다.

실행 순서는 어떻게 정리하나?

다음 순서로 한 단계씩 실행한다. 앞 단계의 출력이 예상과 다르면 다음 명령으로 넘어가지 않는다.

1. git worktree list --porcelain에서 대상이 linked worktree인지 확인한다.
2. 기존 경로의 git status --short를 저장해 수정 파일과 untracked 파일을 기록한다.
3. 새 경로가 없는지 test -e "/새/worktree/경로"로 확인한다.
4. git worktree move에 기존 경로와 새 경로를 모두 적는다.
5. 새 경로에서 브랜치, status, 파일 내용을 다시 확인한다.
6. 원본 저장소의 worktree 목록에서 이전 경로가 사라지고 새 경로가 등록됐는지 확인한다.

test -e가 성공하면 새 경로가 이미 있다는 뜻이다. 그 폴더를 덮지 말고 다른 이름을 고른다. worktree move가 실패했는데 기존 경로가 그대로 있다면 오류 문구를 보존하고, 경로와 권한 또는 submodule 여부를 먼저 해결한다.

자주 묻는 질문

일반 mv로 폴더 이름만 바꾸면 안 되나?

일반 mv는 Git의 worktree 등록 경로를 함께 갱신하지 않는다. linked worktree라면 git worktree move를 우선 사용해 파일 이동과 등록 경로 변경을 한 명령으로 처리한다. 이미 수동 이동했다면 같은 명령을 반복하기 전에 공식 문서의 repair 조건을 확인한다.

수정 중인 파일이 있으면 move가 실패하나?

이번 Git 2.38.1 재현에서는 수정된 추적 파일과 untracked 파일이 있어도 exit 0이었다. 이 결과만으로 모든 버전과 파일 시스템에 일반화하지 않고, 실행 전후 status --short와 필요한 파일 내용을 대조한다.

새 경로가 이미 있으면 어떻게 하나?

기존 폴더를 삭제하거나 강제로 덮지 않는다. 새 경로의 내용을 확인하고 다른 비어 있는 경로를 선택한다. 경로가 정해진 뒤에만 git worktree move를 다시 실행한다.

검증 기준

• 주요 근거: Git 공식 git-worktree 문서
• 공개 질문: How can I rename a git worktree
• 마지막 업데이트일: 2026-09-20
• 확인 환경: macOS 비민감 임시 저장소, Git 2.38.1
• 재현 결과: linked worktree move exit 0, 브랜치 유지, tracked 수정·untracked 파일과 내용 유지, 등록 경로 변경
• 한계: 정확 월간 검색량과 seoin.dev 독자 직접 반응은 미확인이다. main working tree와 submodule 포함 이동 성공은 이번 재현 범위가 아니다.