휴대폰에서 컴퓨터의 Git worktree 관리하기
Git worktree를 원격으로 추가, 전환, 정리하는 실용 가이드. 검토, 작은 수정, 안전한 커밋을 위한 휴대폰 워크플로 포함.
- CLI
- 0.2.17
- 프리뷰 ref
- a2c45c8
Git worktree는 "진지한" Git 사용자를 위한 고급 기능처럼 보일 수 있습니다.
그런데 같은 상황이 계속 반복됩니다.
- 한 변경 작업 중인데
- 작은 핫픽스가 튀어나오거나
- 다른 브랜치를 빠르게 검토해야 하고
- stash/unstash를 반복하고 싶지 않습니다
worktree가 이에 대한 깔끔한 답입니다.
두 번째 깨달음은 더 실용적이었습니다.
휴대폰에서 worktree를 관리할 수 있으면 "자리에 돌아가서 나중에 하자"에서 막히지 않게 된다.
이 가이드는 휴대폰을 제어의 중심으로 하는, 차분하고 반복 가능한 worktree 워크플로입니다.
빠른 정의: worktree란 (쉬운 말로)
Git 리포지토리에는 보통 작업 디렉터리(체크아웃된 파일)가 하나 있습니다.
worktree를 쓰면 리포지토리 하나에 여러 작업 디렉터리를 둘 수 있어서 한 번에 여러 브랜치를 체크아웃할 수 있습니다.
Git 공식 문서는 이를 "같은 리포지토리에 연결된 여러 작업 트리"를 관리해 한 번에 여러 브랜치를 체크아웃할 수 있게 하는 것이라고 설명합니다. (출처: https://git-scm.com/docs/git-worktree)
실제로는:
- 리포지토리의 객체 데이터베이스는 공유됨
- 각 worktree는 자체 체크아웃 파일과 index/HEAD 상태를 가짐
그래서 worktree는 "리포지토리를 두 번 클론"하는 것보다 훨씬 가볍게 느껴집니다.
일반적인 방법과 트레이드오프
핫픽스가 큰 변경을 끊고 들어올 때 흔한 선택지는:
- stash: 되지만 무엇을 왜 stash했는지 잊기 쉬움
- WIP 커밋: 되지만 기록을 더럽히고 실수를 부름
- 다시 클론: 되지만 느리고 많은 것을 중복함
worktree는 메인 브랜치를 깨끗하게 유지하면서 동시에 흐름도 유지하게 해 줍니다.
실제로 쓸 수 있는 워크플로
이 워크플로는 일상적인 Git 제어를 위해 리포지토리를 가진 컴퓨터 위에서 원격 UI를 사용합니다.
Happier는 이 방식을 지원하는 선택지 중 하나입니다.
각 Happier 세션은 컴퓨터의 폴더에 연결되어 있고, 휴대폰에서는 세션이 그 폴더 전용 Files 탭과 Git 탭을 제공합니다. 그러니 worktree 폴더와 그 안의 세션만 있으면 됩니다.
Git 쓰기 작업(커밋, pull, push, 브랜치 전환)은 실험적이며 기본으로 꺼져 있습니다. Settings → Features → Source control operations에서 켭니다(Git 문서 (영어) 참고). 상태와 diff 보기는 이것 없이도 됩니다.
트레이드오프: 컴퓨터가 온라인이어야 합니다.
Happier가 처음이라면 (무엇이고 어디서 받는지)
Happier를 처음 본다면: 신뢰하는 컴퓨터에 워크플로를 두고 휴대폰에서 관리할 수 있게 해 주는 오픈 소스 컴패니언 앱(모바일/웹/데스크톱)입니다.
설정하기:
- 휴대폰에서 Happier 사용하는 방법
- GitHub: https://github.com/happier-dev/happier
- 설치/다운로드: https://github.com/happier-dev/happier#how-it-works
- Discord (커뮤니티 + 지원): https://discord.gg/W6Pb8KuHfg
실수를 막는 사고 모델
휴대폰에서 worktree를 건드리기 전에 두 가지 규칙을 정하세요.
-
worktree 하나 = 목적 하나. 핫픽스가 관련 없는 일이라면 전용 worktree를 쓸 만합니다.
-
휴대폰에서는 작은 수정, 큰 수술은 키보드에서. 휴대폰은 검토, 가벼운 변경, 범위가 좁은 수정 push에 잘 맞습니다.
단계별: 휴대폰에서 worktree 관리하기
1) 리포지토리 폴더에서 세션 열기
리포지토리에서 실행 중인 세션을 열거나, 새 세션을 시작하고 컴퓨터의 리포지토리 폴더를 작업 디렉터리로 고릅니다.
2) Git 탭을 "안전 확인 화면"으로 쓰기
세션 안에서:
- Git 탭 열기
- 변경된 파일부터 시작
이렇게 하면 깔끔하게:
- 무엇이 변경됐는지 검토
- 의도적으로 커밋
- 동기화(Pull/Push)
다음이 보이면:
- Operation requires a clean working tree.
…가드레일로 받아들이세요.
3) 새 worktree 만들기 (핫픽스)
worktree를 만드는 데는 두 가지 생각이 있습니다.
- "새 브랜치용 새 디렉터리가 필요하다"
- "기존 브랜치용 새 디렉터리가 필요하다"
순수 Git으로는 대략:
git worktree add <path>(새 브랜치 간편 생성)- 또는
git worktree add <path> <branch>(기존 브랜치)
(출처: https://git-scm.com/docs/git-worktree)
Happier에서 중요한 건 결과입니다.
- 자체 세션을 시작할 수 있는 두 번째 작업 디렉터리
- 이미 체크아웃된 것을 방해하지 않음
4) 휴대폰 수정은 좁게 유지
worktree가 생기면 휴대폰 루프는:
- 그 worktree에서 실행 중인 세션 열기
- Files로 정확한 파일 검색
- 최소한의 수정
- Save
- Git 탭으로 전환해 diff 검토
- 수정에 속하는 파일만 정확히 골라(0.2.12부터 지원) 작은 변경으로 커밋
5) 핫픽스 push (그리고 멈추기)
핫픽스를 push했으면 멈추세요.
worktree의 가치는 핫픽스가 두 번째 큰 프로젝트로 커지지 않는다는 데 있습니다.
좁게 유지됩니다.
6) worktree 정리 (어수선해지지 않게)
worktree는 강력하지만 쌓일 수 있습니다.
좋은 규칙:
- 브랜치가 병합됐으면 worktree 제거
- 오래 가는 거라면 유지하되 이름을 분명히
순수 Git에서는 worktree가 잘못 삭제된 경우 git worktree prune으로 오래된 관리 파일을 정리할 수 있습니다. (출처: https://git-scm.com/docs/git-worktree)
UI 중심 워크플로에서 목표는 더 단순합니다. 버려진 작업 디렉터리 더미를 남기지 않는 것입니다.
worktree + 여러 에이전트 (이게 중요해진 이유)
worktree는 꽤 오래전부터 있었지만, 에이전트나 세션을 여러 개 병렬로 돌리면 훨씬 유용해집니다.
Claude Code, Codex, OpenCode를 쓴다면 기본 멀티 에이전트 패턴은:
- 작업마다 worktree 하나
- worktree마다 세션 하나
이렇게 하면 격리됩니다.
- 에이전트끼리 파일을 밟지 않음
- diff가 검토하기 쉬움
- 커밋이 좁게 유지됨
Happier에서는 휴대폰을 터미널로 만들지 않고도 이걸 할 수 있습니다.
- worktree 만들기
- 그 worktree 폴더에서 새 세션 시작(Claude/Codex/OpenCode)
- diff, 커밋, 기록을 검토하는 같은 앱에서 세션 모니터링
이건 일부러 "에이전트 10개 동시 실행" 이야기가 아닙니다.
2~3개를 병렬로 돌리고, 검토가 감당 가능하도록 격리하자는 것입니다.
터미널 (선택)
내장 터미널을 쓸 수 있으면 세션에 Terminal 탭이 표시됩니다. 기능 매트릭스 (영어)에 따르면 실험적 기능이며, 연결된 데몬과 접근 가능한 머신이 필요합니다.
터미널은 다음을 위한 비상구로 다루세요.
- UI에 없는 명령 하나
- 간단한 확인
- 무언가 이상한 상태일 때 worktree 정리
모든 걸 터미널에서 하고 있다면, 다음 중 하나를 하라는 신호입니다.
- 워크플로 단순화, 또는
- 키보드를 기다리기
FAQ (실제 worktree 질문)
브랜치와 worktree의 차이는?
브랜치는 포인터(커밋 줄기의 이름)입니다.
worktree는 브랜치를 체크아웃할 수 있는 별도의 작업 디렉터리입니다.
보통 둘을 함께 씁니다. worktree마다 브랜치 하나.
stash 대신 worktree를 쓰는 이유는?
stash는 빠른 맥락 전환에 좋습니다.
worktree는 끼어든 일이 진짜 작업(핫픽스, 검토, 테스트 실행)이고 현재 변경을 밟을 가능성을 0으로 하고 싶을 때 좋습니다.
같은 브랜치를 두 worktree에서 체크아웃할 수 있나요?
기본적으로 Git은 같은 브랜치를 두 worktree에서 동시에 체크아웃하지 못하게 막습니다.
안전 기능입니다.
(브랜치 없이 "테스트만 실행" 같은 작업이라면 detached HEAD worktree를 쓸 수는 있습니다.)
미래의 내가 알아보도록 worktree 이름을 어떻게 지을까요?
목적이 담긴 이름을 쓰세요.
hotfix-<ticket>review-<pr>release-<version>
worktree가 잘못되는 흔한 큰 경우는?
Git 부분이 아닙니다.
사람 부분입니다.
- 어떤 worktree가 "push 안 한 변경이 있는 것"인지 잊음
- 하다 만 핫픽스 worktree를 방치함
해결은 간단합니다. worktree를 좁게 유지하고 정리하세요.
휴대폰에서 worktree를 쓰지 말아야 할 때는?
다음을 하려 할 때입니다.
- 충돌 해결
- 대화형 rebase
- 대규모 리팩터링
이것들은 여전히 키보드에서 하는 게 맞습니다.
"worktree is locked"는 무슨 뜻인가요?
Git에서는 worktree를 잠가서 자동으로 prune/정리되지 않게 할 수 있습니다.
worktree가 항상 마운트되지는 않는 디스크나 위치에 있을 때 유용합니다.
"prune"은 무엇을 하고, 언제 필요한가요?
worktree 폴더가 잘못 삭제되면(git worktree remove를 쓰지 않고) Git에 오래된 메타데이터가 남을 수 있습니다.
git worktree prune은 그 오래된 관리 파일을 정리합니다.
worktree 폴더를 직접 지우지 않는다면 거의 필요 없습니다.
오래 가는 브랜치를 분리하는 데도 worktree를 쓸 수 있나요 (핫픽스만이 아니라)?
네, 좋은 사용법입니다.
예:
- 기본 worktree에서
main을 깨끗하게 유지 release/<version>을 전용 worktree에 두기- 오래 가는 리팩터링을 자체 worktree에 두기
맥락 전환이 줄고 빠른 검토가 쉬워집니다.
worktree끼리 node_modules/빌드 산출물을 공유하나요?
자동으로는 아닙니다.
각 worktree는 별도 디렉터리라서 대부분의 도구는 별도 프로젝트 폴더로 취급합니다.
캐시를 공유하고 싶다면 보통 Git이 아니라 언어/도구 계층(pnpm store, Gradle 캐시 등)에서 처리합니다.
worktree 폴더는 어디에 둬야 하나요?
메인 리포지토리 폴더 옆에 분명한 이름으로 두세요.
예:
repo/(메인 worktree)repo--hotfix-123/repo--release-1.2/
좋은 이름 규칙은 휴대폰 화면에서 무엇을 보고 있는지 바로 알 수 있게 하는 규칙입니다.
휴대폰에서 worktree를 안전하게 제거할 수 있나요?
네, 하지만 먼저 안전 규칙 하나를 지키세요.
- 커밋하지 않은 변경이 없는지 확인
- 아직 필요한 push 안 한 커밋도 없는지 확인
제거 전에 "Changed files"를 빠르게 검토하는 건 값싼 보험입니다.
git worktree는 git switch / git checkout과 같은 건가요?
아니요.
switch/checkout은 하나의 작업 디렉터리가 가리키는 브랜치를 바꿉니다.worktree add는 전환하지 않아도 되도록 두 번째 작업 디렉터리를 만듭니다.
브랜치 대신 worktree를 써야 하나요?
아니요. worktree는 브랜치를 보완합니다.
좋은 기본값은 여전히:
- worktree마다 브랜치 하나
서브모듈과 함께 worktree를 쓸 수 있나요?
네, 하지만 조심하세요. 각 worktree는 자체 체크아웃 상태를 가집니다.
서브모듈이 워크플로의 일부라면 휴대폰 변경은 좁게 유지하고, 더 깊은 "서브모듈 수술"은 키보드에서 하세요.