> ## 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은 **같은 브랜치를 둘 이상의 워크트리가 동시에 체크아웃하는 것**을 막습니다. 그래서 어떤 브랜치가 이미 다른 워크트리의 HEAD로 나가 있으면, 그 브랜치를 현재 워크트리로 체크아웃하려는 시도는 Git 단에서 실패합니다.

ParalleLane은 이 실패를 빨간 에러로 던지는 대신, **그 브랜치를 점유한 워크트리로 전환할지 묻는 확인 모달**로 바꿔 줍니다.

<Steps>
  <Step title="점유된 브랜치를 체크아웃 시도">
    사이드바나 그래프에서 브랜치를 체크아웃합니다. 그 브랜치가 이미 다른 워크트리에 나가 있으면 Git 체크아웃이 실패합니다.
  </Step>

  <Step title="전환 확인 모달 표시">
    ParalleLane은 stderr 메시지를 추측으로 파싱하지 않고, 실제 `git worktree list`로 그 브랜치를 점유한 워크트리를 확인합니다. 확인되면 **"다른 워크트리로 전환"** 모달이 뜹니다. "이 브랜치는 다른 워크트리에서 사용 중입니다"라는 안내와 함께 대상 워크트리·브랜치가 표시됩니다. 이 모달의 화면은 [브랜치 체크아웃](/history/checkout)에서 확인할 수 있습니다.
  </Step>

  <Step title="전환 또는 취소">
    **전환**을 누르면 해당 워크트리로 이동합니다(그 워크트리는 이미 그 브랜치에 있으므로 별도의 체크아웃은 필요 없습니다). 초록색 정보 토스트로 전환 결과를 알려 줍니다. **취소**를 누르면 아무 변화 없이 모달만 닫힙니다.
  </Step>
</Steps>

<Note>
  현재 워크트리가 이미 그 브랜치에 있다면(같은 브랜치 재클릭) 아무 동작도 하지 않습니다. 또 현재 워크트리에 커밋하지 않은 변경(dirty)이 있으면, 점유 여부를 따지기 전에 먼저 로컬 변경 처리 방식을 고르는 체크아웃 모달을 거칩니다(선택지는 [체크아웃 모달 (로컬 변경 처리)](/history/checkout#체크아웃-모달-로컬-변경-처리) 참고). 워킹 카피(Working copy)가 깨끗하면 모달 없이 곧바로 체크아웃을 시도하므로, 점유 확인 모달이 바로 뜹니다.
</Note>

<Tip>
  상단 브레드크럼(`프로젝트 ⟩ 워크트리 ⟩ 브랜치`)을 보면 지금 어느 워크트리의 어느 브랜치에 있는지 항상 확인할 수 있어, 점유 상황을 미리 파악하기 쉽습니다.
</Tip>

## 유령·무효 워크트리 정리하기

다른 도구가 워크트리를 정리하다 실패하거나, 워크트리 폴더가 외부에서 삭제되면 어중간한 잔재가 남습니다. ParalleLane은 이런 워크트리를 상태에 따라 두 가지로 나눠 다룹니다.

<AccordionGroup>
  <Accordion title="유령(prunable) 워크트리 — 디렉터리가 사라짐" icon="ghost">
    작업 디렉터리는 사라졌지만 `.git/worktrees/<id>/` 메타데이터만 남은 상태입니다. `git worktree list`가 이를 `prunable`로 표시합니다. 사이드바에서는 흐리게 표시되고 **존재하지 않음(Missing)** 배지가 붙습니다.

    <Frame>
      <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/worktree-prunable.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=43f3b6ed9a33bfeb80727e137f25cb3f" alt="사이드바의 유령 워크트리 행 클로즈업. 폴더 아이콘과 브랜치 이름이 흐리게 표시되고 오른쪽에 유령 아이콘과 '존재하지 않음(Missing)' 배지가 붙어 있다" width="518" height="72" data-path="images/worktree-prunable.png" />
    </Frame>

    유령 워크트리 행을 클릭하면(에러 대신) 모달 없이 경고 토스트가 뜹니다. 앱 문구 그대로 **"워크트리 디렉토리가 없습니다"** 라는 안내와 함께 **"정리하기"** 액션 버튼이 나타나고, 누르면 그 저장소의 유령 워크트리 전부를 `git worktree prune`으로 정리한 뒤 `워크트리 3개 정리됨`처럼 제거된 개수를 토스트로 알려 줍니다. 정리 후 사이드바 목록이 갱신되어 유령 행이 사라집니다. 유령 행은 클릭해도 **선택되지 않으므로**, 지금 보고 있는 워크트리는 그대로 유지됩니다.
  </Accordion>

  <Accordion title="도달 불가(찾을 수 없음) 워크트리 — 목록에서 이미 빠짐" icon="unlink">
    선택 중이던 워크트리가 외부 삭제·정리 등으로 Git의 `worktree list`에서 완전히 빠진 상태입니다. ParalleLane이 워크트리 목록을 다시 읽었을 때(또는 그 워크트리의 데이터 조회가 "없음"으로 실패해 목록을 재확인했을 때) 선택 중인 워크트리가 사라져 있으면, **선택을 해제하고** "워크트리를 찾을 수 없음" 경고 토스트를 한 번 띄웁니다. 토스트에는 **"정리"** 액션 버튼이 함께 붙습니다.

    이 버튼을 누르면 그 워크트리로 키된 잔여 캐시 상태(그래프·저장소 개요·워킹 카피 상태·그래프 스코프·LFS·되돌리기 기록)를 먼저 비우고, 안전망으로 prune을 실행한 뒤 목록을 다시 조회해 낡은 행을 제거합니다. 끝나면 "워크트리 정리됨" 토스트가 뜹니다. prune이 실패해도 재조회는 그대로 진행됩니다.
  </Accordion>
</AccordionGroup>

### 설정에서 일괄·자동 정리

<Steps>
  <Step title="설정 열기">
    `설정 → ParalleLane → 일반(General)` 으로 이동합니다.
  </Step>

  <Step title="지금 정리 또는 자동 정리">
    * **지금 정리(Prune now)**: **잘못된 워크트리(Invalid worktrees)** 항목의 이 버튼을 누르면 등록된 모든 저장소의 유령 워크트리를 일괄 정리하고, 제거된 개수를 토스트로 알려 줍니다.
    * **잘못된 워크트리 자동 정리(Automatically prune invalid worktrees)** 토글(기본 꺼짐): 켜 두면 워크트리 목록을 읽을 때마다 유령 워크트리를 자동으로 정리합니다.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/worktree-prune-settings.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=2474cfa160fe54d3ac14644aa4196e97" alt="설정 → ParalleLane → 일반(General)의 잘못된 워크트리(Invalid worktrees) 설정 행 한 줄만 잘라낸 클로즈업. 굵은 제목과 유령 워크트리 정리 설명 문구가 왼쪽에 있고, 같은 줄 오른쪽 끝에 지금 정리(Prune now) 버튼과 라벨 없는 자동 정리 토글이 꺼진 상태로 나란히 놓여 있다" width="2224" height="158" data-path="images/worktree-prune-settings.png" />
</Frame>

<Warning>
  정리(prune)는 **작업 디렉터리가 실제로 사라진** 유령 워크트리만 제거합니다. 디스크에 살아 있는 워크트리(잠긴 워크트리 포함)는 절대 건드리지 않으므로, 진행 중인 다른 작업 공간이 정리로 삭제될 걱정은 없습니다.

  다만 살아 있는 워크트리를 직접 지우는 것은 정리가 아니라 [삭제](/worktrees/managing) 흐름이며, 강제 삭제 시 커밋하지 않은 변경이 사라질 수 있으니 구분해서 사용하세요. 잠긴 워크트리를 지우려면 [잠긴 워크트리 삭제 실패와 재시도](/worktrees/managing#잠긴-워크트리-삭제-실패와-재시도)를 참고하세요.
</Warning>