Git 브랜치와 Worktree

Git의 브랜치(Branch) 와 워크트리(Worktree) 는 서로 대체하는 기능이 아닙니다. 브랜치는 작업 이력을 분리하고, Worktree는 하나의 Git 저장소에 연결된 여러 작업 디렉터리에서 서로 다른 브랜치를 동시에 사용할 수 있게 합니다.

기능 개발과 긴급 수정처럼 여러 작업을 병행할 때 Worktree를 사용하면 현재 작업을 커밋하거나 stash한 뒤 브랜치를 전환하는 과정을 줄일 수 있습니다.

브랜치와 Worktree의 차이

브랜치

브랜치는 특정 커밋을 가리키는 이름입니다. 기능 개발을 시작할 때 다음과 같이 브랜치를 만들 수 있습니다.

git checkout -b feature/login

git checkout -b는 새 브랜치를 생성하면서 해당 브랜치로 이동합니다. 같은 작업은 git switch -c로도 수행할 수 있습니다.

git switch -c feature/login

일반적인 Git 저장소는 하나의 작업 디렉터리를 사용하므로 다른 브랜치로 이동하려면 git checkout을 실행해야 합니다. 브랜치 이동만을 목적으로 한다면 git switch도 사용할 수 있습니다.

project/
└── 현재 브랜치: dev

git checkout feature/login

project/
└── 현재 브랜치: feature/login

작업 중인 파일이 브랜치 전환으로 덮어써질 가능성이 있으면 Git은 전환을 거부합니다. 이때는 변경 내용을 커밋하거나 git stash로 임시 저장해야 합니다.

Worktree

Worktree는 하나의 저장소에 별도의 작업 디렉터리를 추가하는 기능입니다. 각 Worktree는 서로 다른 브랜치를 체크아웃할 수 있습니다.

C:\Workspace\project
└── dev

C:\Workspace\Worktrees\project-feature-login
└── feature/login

두 디렉터리의 파일과 작업 상태는 분리되지만 커밋, 브랜치, 태그와 같은 Git 객체는 같은 저장소에서 공유합니다.

구분	브랜치만 사용	Worktree 사용
작업 디렉터리	하나	여러 개
브랜치 이동	git checkout 필요 (git switch도 가능)	디렉터리 또는 IDE 창 이동
미완료 작업 유지	커밋 또는 stash가 필요할 수 있음	각 Worktree에 그대로 유지
여러 작업 병행	불편할 수 있음	편리함
저장소 객체	하나	하나를 공유
디스크 사용량	상대적으로 적음	각 Worktree의 파일만큼 증가

Worktree는 저장소를 다시 clone하는 기능이 아닙니다. 연결된 Worktree는 공통 저장소를 공유하지만, 각 Worktree의 HEAD, 인덱스, 작업 파일 등은 별도로 관리됩니다.

---

Worktree 생성과 구조

새로운 브랜치와 Worktree를 함께 생성

현재 저장소가 dev 브랜치를 사용하고 있고, 이를 기준으로 feature/login을 만들려면 다음과 같이 실행합니다.

git fetch origin
git worktree add -b feature/login ../project-feature-login origin/dev

명령의 의미는 다음과 같습니다.

부분	의미
git worktree add	연결된 Worktree 생성
-b feature/login	새 브랜치 생성
../project-feature-login	새 작업 디렉터리 경로
origin/dev	새 브랜치의 시작 커밋

로컬 dev가 최신임을 확인했다면 origin/dev 대신 dev를 기준으로 만들 수 있습니다.

git worktree add -b feature/login ../project-feature-login dev

이미 존재하는 브랜치로 생성

feature/login 브랜치가 이미 존재한다면 -b를 사용하지 않습니다.

git worktree add ../project-feature-login feature/login

원격 브랜치만 있고 로컬 브랜치가 없다면 다음처럼 로컬 추적 브랜치를 만들면서 Worktree를 생성할 수 있습니다.

git fetch origin
git worktree add -b feature/login ../project-feature-login origin/feature/login

경로 예시

Windows에서 프로젝트와 Worktree를 구분해서 관리할 수 있습니다.

C:\Workspace\Projects\sample
C:\Workspace\Worktrees\sample-feature-login
C:\Workspace\Worktrees\sample-hotfix-auth

원본 저장소 내부에 Worktree를 만들기보다 형제 디렉터리나 별도의 Worktrees 디렉터리를 사용하는 편이 구조를 파악하기 쉽습니다.

.git 구조

기본 작업 디렉터리에는 일반적으로 .git 디렉터리가 존재합니다.

project/
├── .git/
└── src/

연결된 Worktree의 .git은 보통 디렉터리가 아니라 실제 Git 관리 디렉터리를 가리키는 파일입니다.

project-feature-login/
├── .git
└── src/

따라서 연결된 Worktree의 .git 파일이나 기본 저장소의 .git/worktrees 내용을 수동으로 삭제하거나 수정해서는 안됩니다. Worktree 제거와 복구에는 Git 명령을 사용해야 합니다.

---

IntelliJ IDEA에서 Worktree 사용

IntelliJ IDEA는 Git Worktree를 생성하고 열 수 있는 기능을 제공합니다.

IntelliJ IDEA에서 생성

버전에 따라 메뉴 이름과 위치가 조금 다를 수 있지만 일반적인 흐름은 다음과 같다.

1. 프로젝트의 Git 브랜치 메뉴 또는 Git 도구 창을 엽니다.
2. 기준 브랜치를 선택합니다.
3. New Worktree 또는 Create Worktree를 선택합니다.
4. Worktree 경로와 사용할 브랜치를 지정합니다.
5. 생성한 Worktree를 현재 창 또는 새 창에서 엽니다.

터미널에서 다음 명령을 실행한 것과 같은 구조가 만들어집니다.

git worktree add -b feature/login ../project-feature-login dev

하나의 IntelliJ IDEA에서 이동

Worktree 전환은 같은 디렉터리에서 브랜치를 바꾸는 동작이 아닙니다. 서로 다른 프로젝트 디렉터리를 여는 동작입니다.

열기 방식은 일반적으로 다음과 같이 구분할 수 있습니다.

방식	동작	사용 상황
현재 창에서 열기	기존 프로젝트를 닫고 다른 Worktree를 현재 창에 표시	IntelliJ 창을 하나만 유지할 때
새 창에서 열기	기존 Worktree를 유지하고 별도 창에 표시	여러 작업을 동시에 확인할 때
Attach	현재 프로젝트에 다른 디렉터리를 추가	서로 다른 프로젝트를 함께 구성할 때

같은 저장소의 Worktree를 Attach하면 동일한 클래스와 Gradle 또는 Maven 모듈이 중복될 수 있습니다. 검색 결과 중복, 모듈 이름 충돌, 실행 설정 혼동, 추가 인덱싱이 발생할 수 있으므로 같은 프로젝트의 Worktree는 독립된 IntelliJ 프로젝트 창으로 여는 편이 안전합니다.

권장 사용 예시

IntelliJ 창 1
C:\Workspace\Projects\sample
└── dev

IntelliJ 창 2
C:\Workspace\Worktrees\sample-feature-login
└── feature/login

IntelliJ 창 3
C:\Workspace\Worktrees\sample-hotfix-auth
└── hotfix/auth

각 창의 터미널에서 다음 명령으로 현재 브랜치를 확인할 수 있습니다.

git branch --show-current

---

Merge와 Rebase

Worktree에서 사용하는 Merge와 Rebase는 일반 브랜치에서 사용하는 방법과 같습니다. Worktree는 작업 디렉터리를 분리할 뿐 커밋 통합 방식을 변경하지 않습니다.

Feature 작업 커밋

Feature Worktree에서 작업을 완료합니다.

cd C:\Workspace\Worktrees\sample-feature-login

git status
git add .
git commit -m "로그인 기능 추가"
git push -u origin feature/login

Feature를 dev에 Merge

feature/login을 dev에 합칠 때는 dev가 체크아웃된 Worktree에서 실행합니다.

cd C:\Workspace\Projects\sample

git branch --show-current
git pull --ff-only origin dev
git merge feature/login
git push origin dev

Merge는 이름으로 지정한 브랜치의 변경 내용을 현재 브랜치에 통합합니다. 따라서 현재 브랜치가 무엇인지 먼저 확인하는 것이 중요합니다.

현재 브랜치: dev

git merge feature/login

feature/login ─────▶ dev

잘못된 Worktree에서 실행하면 의도와 반대 방향으로 Merge할 수 있습니다.

PR로 Merge

보호 브랜치와 코드 리뷰를 사용하는 환경에서는 로컬에서 dev에 직접 Merge하지 않고 PR을 사용하는 것이 일반적입니다.

feature/login에서 작업
        ↓
origin/feature/login으로 Push
        ↓
feature/login → dev PR 생성
        ↓
리뷰 및 테스트
        ↓
Gitea 또는 GitHub에서 Merge
        ↓
dev Worktree에서 최신 내용 Pull

PR이 Merge된 뒤 dev Worktree를 갱신합니다.

cd C:\Workspace\Projects\sample
git checkout dev
git pull --ff-only origin dev

Feature에 최신 dev 반영: Merge 방식

Feature 브랜치에서 기존 커밋 이력을 유지하면서 최신 dev를 반영하려면 Feature Worktree에서 다음과 같이 실행합니다.

git fetch origin
git merge origin/dev

충돌이 발생하면 파일을 수정한 뒤 다음 명령으로 완료합니다.

git add <해결한-파일>
git commit

Merge를 취소하려면 다음 명령을 사용합니다.

git merge --abort

Feature에 최신 dev 반영: Rebase 방식

Feature 커밋을 최신 dev 뒤에 다시 적용해 이력을 직선 형태로 정리하려면 Feature Worktree에서 Rebase합니다.

git fetch origin
git rebase origin/dev

개념적으로 다음과 같이 변경됩니다.

Rebase 전:

A---B---C  dev
     \
      D---E  feature/login

dev에 F가 추가된 뒤 Rebase:

A---B---C---F  dev
             \
              D'---E'  feature/login

D', E'는 기존 변경을 새 기준 위에 다시 적용해서 만들어진 새 커밋이므로 기존 D, E와 커밋 ID가 다릅니다.

충돌이 발생하면 다음 순서로 처리합니다.

git status

# 충돌 파일 수정
git add <해결한-파일>
git rebase --continue

현재 커밋 적용을 건너뛰려면 다음 명령을 사용할 수 있지만, 필요한 변경까지 사라질 수 있으므로 내용을 확인한 뒤 사용합니다.

git rebase --skip

Rebase 시작 전 상태로 되돌리려면 다음 명령을 사용합니다.

git rebase --abort

이미 원격에 Push한 Feature 브랜치를 Rebase했다면 커밋 이력이 변경되므로 일반 Push가 거부될 수 있습니다.

git push --force-with-lease origin feature/login

--force-with-lease도 원격 브랜치 이력을 변경합니다. 여러 사람이 함께 사용하는 브랜치에서는 합의 없이 Rebase와 강제 Push를 사용하지 않는 것이 안전합니다.

Merge와 Rebase 선택

구분	Merge	Rebase
기존 커밋 ID	유지	변경
통합 기록	Merge commit이 생길 수 있음	직선 형태로 정리 가능
공유 브랜치	비교적 안전	주의 필요
개인 Feature 브랜치	사용 가능	PR 전 정리에 유용
충돌 해결	한 번에 통합하는 경우가 많음	커밋별로 여러 번 발생할 수 있음

팀에서 정한 정책이 없다면 공유된 브랜치에는 Merge를 사용하고, 개인 Feature 브랜치는 PR을 만들기 전에 Rebase로 정리하는 방식을 고려할 수 있습니다.

---

Worktree 관리와 오류 해결

Worktree 목록 확인

git worktree list

예시:

C:/Workspace/Projects/sample                         a1b2c3d [dev]
C:/Workspace/Worktrees/sample-feature-login          d4e5f6a [feature/login]
C:/Workspace/Worktrees/sample-hotfix-auth             1122abc [hotfix/auth]

상세한 기계 판독 형식이 필요하면 다음 명령을 사용할 수 있습니다.

git worktree list --porcelain

Worktree 제거

작업 파일에 미커밋 변경이 없는지 먼저 확인합니다.

cd C:\Workspace\Worktrees\sample-feature-login
git status

기본 저장소나 다른 Worktree에서 제거합니다.

git worktree remove C:\Workspace\Worktrees\sample-feature-login

미커밋 변경이나 추적되지 않은 파일이 있으면 Git이 제거를 거부할 수 있습니다. --force로 강제 제거할 수도 있지만 작업 내용이 삭제될 수 있으므로 먼저 커밋, Push 또는 백업 여부를 확인해야 합니다.

git worktree remove --force C:\Workspace\Worktrees\sample-feature-login

remove와 prune의 차이

명령	역할
git worktree remove <경로>	Git이 Worktree 디렉터리와 연결 정보를 정상적으로 제거
git worktree prune	이미 외부에서 삭제되어 유효하지 않은 Worktree 관리 정보를 정리

Worktree 디렉터리를 파일 탐색기에서 먼저 삭제했다면 Git에는 연결 정보가 남을 수 있습니다.

git worktree list
git worktree prune

실제로 정리될 항목을 먼저 확인하려면 다음 명령을 사용할 수 있습니다.

git worktree prune --dry-run --verbose

이미 다른 Worktree에서 사용 중인 브랜치

같은 브랜치를 일반적인 방식으로 두 Worktree에 동시에 체크아웃하려고 하면 Git이 거부합니다.

예시 오류:

fatal: 'feature/login' is already checked out at
'C:/Workspace/Worktrees/sample-feature-login'

먼저 현재 위치를 확인합니다.

git worktree list

해결 방법은 다음 중 하나다.

1. 해당 브랜치가 이미 체크아웃된 Worktree를 사용합니다.
2. 기존 Worktree를 제거한 뒤 새 경로에 다시 만듭니다.
3. 새 브랜치를 만들어 별도 Worktree에서 사용합니다.

git worktree add -b feature/login-fix ../sample-feature-login-fix feature/login

Git에는 강제 옵션이 있지만 동일 브랜치를 여러 Worktree에서 수정하면 작업 상태를 혼동하거나 서로 덮어쓰는 문제가 생길 수 있으므로 일반적인 개발 흐름에서는 피하는 것이 좋습니다.

Worktree 이동

Git 명령으로 Worktree 경로를 이동할 수 있습니다.

git worktree move \
  C:\Workspace\Worktrees\sample-feature-login \
  D:\GitWorktrees\sample-feature-login

운영체제 파일 탐색기로 임의 이동했다면 연결 정보가 어긋날 수 있습니다. 가능한 경우 git worktree move를 사용합니다.

이동 또는 복사 후 연결 복구

기본 저장소나 연결된 Worktree의 경로를 수동으로 이동하여 연결 정보가 잘못되었다면 repair를 사용할 수 있습니다.

git worktree repair

특정 경로를 지정할 수도 있습니다.

git worktree repair D:\GitWorktrees\sample-feature-login

repair는 잘못 연결된 Worktree 메타데이터를 복구하기 위한 명령이며 삭제된 작업 파일을 되살리는 명령은 아닙니다.

Worktree 잠금

Worktree가 이동식 디스크나 네트워크 경로에 있어 일시적으로 접근할 수 없을 때 prune으로 정리되지 않도록 잠글 수 있습니다.

git worktree lock --reason "외장 SSD에 보관" D:\GitWorktrees\sample-feature-login

잠금 해제:

git worktree unlock D:\GitWorktrees\sample-feature-login

일반적인 로컬 개발 Worktree에는 잠금이 필수는 아닙니다.

Merge 후 안전하게 정리

PR 또는 Merge가 완료된 뒤 다음 순서로 정리합니다.

# dev Worktree에서 최신 상태 반영
cd C:\Workspace\Projects\sample
git pull --ff-only origin dev

# Feature가 dev에 포함되었는지 확인
git branch --merged dev

# Worktree 제거
git worktree remove C:\Workspace\Worktrees\sample-feature-login

# 로컬 브랜치 삭제
git branch -d feature/login

# 필요한 경우 원격 브랜치 삭제
git push origin --delete feature/login

git branch -d는 브랜치가 현재 브랜치에 Merge되지 않았다고 판단하면 삭제를 거부합니다. 확인 없이 -D로 강제 삭제하면 미반영 커밋을 잃을 수 있으므로 주의합니다.

---

dev → stg → main 운영 예시

다음과 같은 브랜치 흐름을 사용하는 프로젝트를 가정합니다.

feature/* → dev → stg → main

Worktree는 기능별 작업 디렉터리를 분리하는 데 사용하고, 배포 브랜치 통합은 PR 정책에 따라 수행합니다.

디렉터리 구성

C:\Workspace\Projects\sample
└── dev

C:\Workspace\Worktrees\sample-feature-order
└── feature/order

C:\Workspace\Worktrees\sample-feature-payment
└── feature/payment

C:\Workspace\Worktrees\sample-hotfix-auth
└── hotfix/auth

모든 장기 브랜치에 Worktree를 만들 필요는 없습니다. 평소에는 dev와 현재 작업 중인 Feature Worktree만 유지하고, stg나 main을 직접 확인해야 할 때 추가하는 방식이 관리하기 쉽습니다.

Feature 개발 흐름

# dev 기준 Feature Worktree 생성
git fetch origin
git worktree add -b feature/order \
  C:\Workspace\Worktrees\sample-feature-order \
  origin/dev

Feature Worktree에서 작업합니다.

cd C:\Workspace\Worktrees\sample-feature-order

git add .
git commit -m "주문 조회 기능 추가"
git push -u origin feature/order

그다음 Gitea 또는 GitHub에서 feature/order → dev PR을 만듭니다.

PR이 Merge된 후 dev Worktree를 갱신합니다.

cd C:\Workspace\Projects\sample
git pull --ff-only origin dev

dev에서 stg, stg에서 main으로 승격

feature/order
      ↓ PR
dev
      ↓ PR
stg
      ↓ 검증 및 PR
main

이 흐름에서 Worktree는 PR을 대체하지 않습니다. Worktree는 로컬 작업 환경을 분리하고, PR은 원격 저장소에서 리뷰와 브랜치 통합을 관리합니다.

긴급 수정

운영 기준 브랜치가 main이라면 Hotfix는 최신 main에서 분기하는 것이 일반적입니다.

git fetch origin
git worktree add -b hotfix/auth \
  C:\Workspace\Worktrees\sample-hotfix-auth \
  origin/main

수정 후 hotfix/auth → main PR을 만들고, 운영 반영이 끝나면 같은 수정이 stg와 dev에도 포함되도록 팀 정책에 따라 Merge 또는 Cherry-pick합니다.

hotfix/auth → main
           ├→ stg 반영
           └→ dev 반영

운영 수정이 main에만 남으면 이후 dev → stg → main 과정에서 코드가 다시 달라지거나 충돌할 수 있습니다.

Worktree가 특히 유용한 상황

• Feature 개발 중 운영 Hotfix를 즉시 처리해야 할 때
• 서로 다른 Feature를 동시에 테스트해야 할 때
• dev, stg, main의 설정이나 결과를 나란히 비교해야 할 때
• 장시간 실행 중인 로컬 서버를 유지하면서 다른 브랜치를 수정해야 할 때
• 미완료 작업 때문에 git checkout 또는 git switch가 어려울 때

Worktree를 과도하게 만들면 디스크 사용량과 IntelliJ 인덱싱 대상이 늘어납니다. 실제로 동시에 필요한 작업만 유지하고 완료된 Worktree는 정리하는 것이 좋습니다.

---

명령어 정리

목적	명령
새 브랜치와 Worktree 생성	git worktree add -b feature/login ../project-feature-login dev
기존 브랜치로 생성	git worktree add ../project-feature-login feature/login
원격 브랜치 기준 생성	git worktree add -b feature/login ../project-feature-login origin/feature/login
목록 확인	git worktree list
상세 목록 확인	git worktree list --porcelain
Worktree 이동	git worktree move <기존 경로> <새 경로>
Worktree 제거	git worktree remove <경로>
잘못된 관리 정보 정리	git worktree prune
정리 대상 미리 확인	git worktree prune --dry-run --verbose
연결 정보 복구	git worktree repair [경로]
Worktree 잠금	git worktree lock --reason "이유" <경로>
잠금 해제	git worktree unlock <경로>
기존 브랜치로 이동	git checkout <브랜치명> (git switch <브랜치명>도 가능)
새 브랜치 생성 후 이동	git checkout -b <브랜치명> (git switch -c <브랜치명>도 가능)
현재 브랜치 확인	git branch 또는 git branch --show-current
Feature에 dev Merge	git merge origin/dev
Feature를 dev 위로 Rebase	git rebase origin/dev
Merge 취소	git merge --abort
Rebase 계속	git rebase --continue
Rebase 취소	git rebase --abort
안전한 강제 Push	git push --force-with-lease

git checkout은 브랜치 이동뿐 아니라 파일 복원 등 여러 기능을 함께 제공하는 기존 명령입니다. git switch는 브랜치 생성과 이동 목적을 더 명확하게 구분하기 위해 추가된 명령입니다. 이 문서에서는 브랜치 이동의 기본 예제를 git checkout으로 작성하되, 같은 작업을 git switch로도 수행할 수 있도록 함께 표기했습니다.

브랜치는 작업 이력을 분리하고 Worktree는 작업 공간을 분리합니다. Worktree에서도 커밋, Push, Merge, Rebase, PR 방식은 일반 브랜치와 동일합니다. 차이는 브랜치마다 별도의 디렉터리와 IntelliJ 창을 유지할 수 있다는 점입니다.

여러 기능과 긴급 수정을 병행하는 프로젝트에서는 다음 원칙으로 운영하면 관리하기 쉽습니다.

브랜치로 변경 이력을 분리합니다.
Worktree로 작업 디렉터리를 분리합니다.
PR로 공유 브랜치에 통합합니다.
작업이 끝난 Worktree는 제거합니다.

---

참고 자료

• Git Worktree 공식 문서: https://git-scm.com/docs/git-worktree
• Git Merge 공식 문서: https://git-scm.com/docs/git-merge
• Git Rebase 공식 문서: https://git-scm.com/docs/git-rebase
• Git Branch 공식 문서: https://git-scm.com/docs/git-branch
• Git Switch 공식 문서: https://git-scm.com/docs/git-switch
• IntelliJ IDEA Git Worktree 문서: https://www.jetbrains.com/help/idea/use-git-worktrees.html
• IntelliJ IDEA Git 브랜치 관리 문서: https://www.jetbrains.com/help/idea/manage-branches.html
• IntelliJ IDEA 충돌 해결 문서: https://www.jetbrains.com/help/idea/resolve-conflicts.html