> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallelane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 워크트리란?

> 워크트리 개념과 활용

워크트리는 ParalleLane이 가장 강조하는 핵심 개념입니다. 하나의 저장소에서 여러 브랜치를 각각 다른 폴더에 동시에 펼쳐 놓고, 마치 별개의 작업 공간처럼 나란히 다룰 수 있게 해 줍니다.

## 워크트리란 무엇인가요?

일반적인 Git 사용에서는 저장소 하나에 작업 트리(working tree)가 하나뿐입니다. 그래서 브랜치를 바꾸려면 매번 `checkout`으로 같은 폴더의 내용을 통째로 바꿔야 하죠. 작업하던 브랜치를 잠시 두고 다른 브랜치를 봐야 할 때, 커밋하거나 stash로 변경사항을 치워야 하는 번거로움이 여기서 옵니다.

**Git worktree**는 이 제약을 풀어 줍니다. 하나의 저장소(`.git` 히스토리는 공유)에 대해 **여러 개의 작업 트리**를 서로 다른 폴더에 두고, 각 폴더에 서로 다른 브랜치를 동시에 체크아웃해 둘 수 있습니다.

<Note>
  저장소를 처음 열었을 때의 원래 작업 트리를 **기본 워크트리**(primary worktree)라고 부릅니다. `git worktree add`로 추가로 만든 폴더는 **연결된(linked) 워크트리**입니다. 커밋 히스토리와 브랜치는 모든 워크트리가 함께 공유하지만, 각 폴더에 체크아웃된 브랜치와 작업 중인 변경사항은 서로 독립적입니다.
</Note>

핵심 규칙 하나만 기억하세요. **같은 브랜치를 두 워크트리가 동시에 체크아웃할 수는 없습니다.** Git이 이를 막아 줍니다. 이미 다른 워크트리가 점유한 브랜치로 이동하려 할 때 ParalleLane이 어떻게 도와주는지는 [점유 브랜치 & 정리](/worktrees/advanced)에서 다룹니다.

## 언제 유용한가요?

<CardGroup cols={2}>
  <Card title="코드 리뷰" icon="eye">
    작업 중인 브랜치를 그대로 둔 채, 동료의 브랜치를 별도 폴더에 체크아웃해 실제로 빌드하고 실행하며 리뷰할 수 있습니다.
  </Card>

  <Card title="긴급 핫픽스" icon="flame">
    기능 작업 도중 급한 버그가 들어와도, stash 없이 새 워크트리에서 `main` 기반 핫픽스를 진행하고 원래 작업으로 그대로 돌아옵니다.
  </Card>

  <Card title="병렬 작업" icon="layout-grid">
    두세 개의 기능을 각각의 폴더에서 동시에 진행합니다. 빌드 산출물이나 의존성이 서로 섞이지 않습니다.
  </Card>

  <Card title="장시간 실행 비교" icon="git-compare">
    한 브랜치에서 테스트를 오래 돌리는 동안, 다른 워크트리에서 방해받지 않고 계속 코드를 작성할 수 있습니다.
  </Card>
</CardGroup>

<Tip>
  브랜치 전환이 잦거나, 자동화 도구(예: 에이전트 기반 워크스페이스)가 워크트리를 대량으로 만들어 두는 환경이라면 워크트리는 특히 큰 힘을 발휘합니다.
</Tip>

## ParalleLane은 워크트리를 어떻게 다루나요?

많은 Git 클라이언트에서 워크트리는 숨겨진 고급 기능이지만, ParalleLane은 이를 **1급 개념**으로 전면에 내세웁니다.

<AccordionGroup>
  <Accordion title="사이드바에 워크트리를 직접 표시" icon="panel-left">
    좌측 사이드바에서 각 저장소 아래에 그 저장소의 워크트리들이 나열됩니다. 기본 워크트리는 폴더 체크 아이콘, 연결된 워크트리는 Git 폴더 아이콘으로 구분되며, 각 행은 체크아웃된 브랜치(또는 분리된 HEAD의 짧은 SHA)와 앞섬/뒤처짐(ahead/behind) 정보를 보여 줍니다. 워크트리 행을 클릭하면 그 워크트리로 전환됩니다.

    <Frame>
      <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/worktree-sidebar.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=20dc70c8235d8b2a56a3b269042d0c3c" alt="좌측 사이드바 프로젝트 탭에 한 저장소의 워크트리 다섯 개가 나열되어 있다. 맨 위 기본 워크트리는 폴더 체크 아이콘, 나머지 연결된 워크트리는 Git 폴더 아이콘으로 구분되고, 행마다 체크아웃된 브랜치 이름이 있으며 앞섬/뒤처짐이 있는 행에는 개수가 오른쪽에 붙어 있다" width="2266" height="1784" data-path="images/worktree-sidebar.png" />
    </Frame>
  </Accordion>

  <Accordion title="워크트리별 독립 커밋 그래프" icon="git-branch">
    ParalleLane의 상징인 스트리밍 커밋 그래프는 워크트리마다 따로 계산되고 캐시됩니다. 그래프에 어떤 범위의 브랜치가 그려지는지는 워크트리 종류에 따라 다릅니다 — 자세한 규칙은 [그래프 스코프: 현재 브랜치 vs 모든 브랜치](/worktrees/status#그래프-스코프-현재-브랜치-vs-모든-브랜치)에서 다룹니다.
  </Accordion>

  <Accordion title="워크트리별 독립 상태" icon="list-checks">
    각 워크트리는 자신만의 커밋 그래프 캐시, 저장소 개요(로컬·원격 브랜치, 태그, 스태시), 워킹 카피 상태를 따로 유지합니다. 우측 사이드바 최상단의 **워킹 카피(Working copy)** 카드는 현재 선택한 워크트리의 충돌/변경 상태를 즉시 알려 줍니다.
  </Accordion>

  <Accordion title="상단 브레드크럼으로 위치 확인" icon="navigation">
    콘텐츠 영역의 상단 바는 연결된 워크트리를 보고 있을 때 `프로젝트 ⟩ 워크트리 ⟩ 브랜치` 형태로 경로를 표시해, 지금 어느 워크트리의 어느 브랜치에 있는지 한눈에 알 수 있습니다.
  </Accordion>
</AccordionGroup>

## 이 그룹에서 다루는 내용

<CardGroup cols={2}>
  <Card title="워크트리 생성·전환·삭제" icon="folder-plus" href="/worktrees/managing">
    새 워크트리를 만들고, 사이드바에서 전환하고, 안전하게 삭제하는 방법을 안내합니다.
  </Card>

  <Card title="워크트리별 상태" icon="activity" href="/worktrees/status">
    우측 사이드바 상태 표시, 워크트리별 독립 그래프·탭·상태, 사이드바 행 표기 규칙을 설명합니다.
  </Card>

  <Card title="점유 브랜치 & 워크트리 정리" icon="eraser" href="/worktrees/advanced">
    이미 점유된 브랜치 체크아웃 처리와, 유령·무효 워크트리 감지 및 정리(prune)를 다룹니다.
  </Card>

  <Card title="기본으로 돌아가기" icon="git-commit-horizontal" href="/history/checkout">
    브랜치 체크아웃 등 히스토리 관련 기본 동작이 궁금하다면 여기를 참고하세요.
  </Card>
</CardGroup>