Git worktree 사용법: 작업 중인 코드를 그대로 두고 다른 브랜치 열기

기능을 개발하던 중 문서 수정 요청이 들어오면 현재 파일을 어떻게 정리할지 잠시 고민하게 됩니다. Git worktree는 한 저장소에 여러 작업 폴더를 연결해 서로 다른 브랜치를 동시에 열 수 있는 기능입니다. 원래 폴더의 편집 상태를 유지하면서 별도 폴더에서 다른 일을 할 때 활용할 수 있습니다. 이 글에서는 생성부터 정리까지 작은 문서 작업을 예로 설명합니다.

저장소 하나와 작업 폴더 여러 개

Git 공식 문서는 worktree를 같은 저장소에 연결된 여러 작업 트리로 설명합니다. 연결된 작업 폴더는 저장소의 객체와 일반 브랜치 참조 등을 공유하지만, 각자의 HEAD와 인덱스 등 작업 상태를 가집니다. 여기서 인덱스는 다음 커밋에 넣을 변경을 준비하는 영역입니다. 별도 폴더라고 해서 서로 완전히 무관한 저장소가 되는 것은 아닙니다.

예를 들어 project 폴더는 feature-search 브랜치, project-docs 폴더는 docs-update 브랜치를 사용하도록 구성할 수 있습니다. 두 폴더를 편집기 창 두 개에 각각 열면 위치와 작업 목적을 구분하기 쉽습니다. 아래 이름과 경로는 직접 바꿔 사용할 수 있는 실습 예시입니다.

구분	원래 작업 폴더	새 작업 폴더
폴더 예시	project	project-docs
브랜치 예시	feature-search	docs-update
작업 목적	검색 기능 개발	설치 안내 보완
확인할 상태	원래 수정 파일	문서 수정 파일

1단계: 현재 위치와 상태를 확인합니다

먼저 원래 저장소의 터미널에서 다음 명령을 실행합니다. 결과를 보고 현재 브랜치와 수정한 파일을 확인합니다. 이미 작업 폴더가 여럿 있다면 목록에서 같은 목적의 폴더가 있는지도 확인할 수 있습니다.

git status --short
git branch --show-current
git worktree list

원래 폴더에 아직 커밋하지 않은 변경이 있어도, 별도의 브랜치와 작업 폴더를 만드는 흐름을 사용할 수 있습니다. 다만 새 폴더는 선택한 커밋의 내용을 기준으로 시작합니다. 원래 폴더의 미커밋 편집 내용이 자동으로 복사되는 것으로 생각하지 않도록 주의합니다.

2단계: 새 브랜치와 폴더를 함께 만듭니다

다음 명령은 main을 시작점으로 docs-update 브랜치를 만들고, 상위 디렉터리의 project-docs에 연결합니다. 현재 저장소에 main이 실제로 존재하는지 먼저 확인합니다. 팀에서 다른 기본 브랜치를 사용한다면 그 이름을 지정합니다. 원격의 최신 상태가 필요한 작업은 팀의 갱신 절차에 맞춰 기준 커밋을 먼저 확정합니다.

git worktree add -b docs-update ../project-docs main
git -C ../project-docs status --short
git -C ../project-docs branch --show-current

마지막 명령에서 docs-update가 표시되는지 확인합니다. 이미 같은 이름의 브랜치나 폴더가 존재한다면 새 이름을 정하거나 기존 작업의 목적을 확인한 뒤 진행합니다. 강제로 덮어쓰는 옵션 없이 상태를 이해하는 것이 이 예시의 기본 원칙입니다.

3단계: 편집기와 실행 환경을 구분합니다

새 폴더를 편집기에 열고 문서 한 곳을 수정해 보세요. 저장 후 새 폴더에서 git diff를 실행하면 그 작업의 변경을 읽을 수 있습니다. 원래 폴더에서도 상태를 확인해 기존 편집 내용이 그대로 있는지 비교합니다. 각 터미널의 현재 경로를 창 제목이나 프롬프트에 표시해 두면 위치를 확인하기 쉽습니다.

확인 항목	점검 방법	이유
현재 경로	pwd	작업할 폴더 구분
현재 브랜치	git branch --show-current	변경이 속할 브랜치 확인
변경 내용	git diff	실제 수정 범위 검토
추가 파일	git status --short	추적되지 않은 파일 확인

소스 폴더가 나뉘어도 데이터베이스나 서버 포트가 자동 분리되는 것은 아닙니다. 두 개발 서버를 동시에 실행한다면 포트를 각각 지정하고, 환경 파일이 어떤 데이터베이스를 가리키는지 확인합니다. 패키지 설치 결과나 빌드 파일도 프로젝트 구성에 따라 새 폴더에서 준비해야 할 수 있습니다.

4단계: 작업이 끝난 폴더를 정리합니다

문서 변경은 팀의 검토·커밋 절차에 따라 보존합니다. 폴더를 정리하기 전에는 수정 파일과 추적되지 않은 파일을 확인합니다. 아래 remove 명령은 해당 작업 폴더가 더 이상 필요 없고 필요한 변경을 보존한 경우에 실행합니다. 폴더 안에서 실행 중인 편집기나 서버도 정리합니다.

git -C ../project-docs status --short
git worktree remove ../project-docs
git worktree list

기본 remove는 수정 내용 등이 있는 작업 폴더를 곧바로 제거하지 않도록 동작합니다. 제거가 중단되면 강제 옵션을 붙이기보다 남은 파일을 먼저 확인합니다. 작업 폴더 제거와 브랜치 삭제는 서로 다른 작업이므로, 브랜치 정리는 팀의 병합·보존 기준에 맞춰 별도로 판단합니다.

자주 만나는 상황

같은 브랜치를 두 폴더에서 열 수 있나요? 일반적인 add 동작은 이미 다른 worktree에서 체크아웃한 브랜치를 다시 사용하는 것을 제한합니다. 같은 기준 코드를 보고 싶다면 목적에 맞는 별도 브랜치를 만들거나 읽기 검토용 detached 작업 방식을 검토할 수 있습니다. 이 입문 예시에서는 서로 다른 브랜치를 사용합니다.

새 폴더에서 수정한 파일이 원래 폴더에도 즉시 바뀌나요? 각 작업 폴더의 파일 편집은 분리됩니다. 다른 브랜치의 변경을 가져오는 일은 병합 같은 별도 Git 작업으로 수행합니다. 다만 브랜치 참조와 저장소 객체는 공유하므로 저장소 전체에 영향을 주는 명령의 범위는 이해하고 실행합니다.

worktree를 처음 쓸 때는 문서 한 곳을 수정하는 작은 과제로 연습해 보세요. ‘폴더 확인 → 브랜치 확인 → 변경 확인’의 순서만 익혀도 여러 작업을 나란히 관리하는 데 활용할 수 있습니다.

공식 문서 확인: 2026년 9월 17일. 명령은 설명용 예시이며 실제 저장소 이름과 경로에 맞게 적용합니다.
출처: https://git-scm.com/docs/git-worktree