> ## 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은 저장소의 **기본 브랜치**에서 새 브랜치를 만들고, 그 브랜치를 체크아웃한 워크트리 폴더를 한 번에 생성해 줍니다.

<Steps>
  <Step title="+ 버튼 누르기">
    좌측 사이드바에서 저장소(프로젝트) 행 위에 마우스를 올리면 나타나는 **`+` 버튼**(툴팁 "워크트리 추가")을 클릭합니다. **워크트리 생성(Create Worktree)** 다이얼로그가 열립니다.

    <Frame>
      <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/worktree-create-dialog.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=ed64b756478fb2b36216e25db20594f3" alt="워크트리 생성 다이얼로그. 새 브랜치 이름 입력란, 자동으로 채워진 워크트리 경로와 찾아보기 버튼, 그 아래 기준 브랜치 표시가 보인다" width="886" height="632" data-path="images/worktree-create-dialog.png" />
    </Frame>
  </Step>

  <Step title="새 브랜치 이름 입력">
    만들 **새 브랜치 이름**을 입력합니다. 다이얼로그 아래쪽에는 기준이 되는 브랜치가 `기준: main`처럼 표시됩니다. 기준 브랜치는 `origin/HEAD`가 가리키는 로컬 브랜치 → 로컬 `main` → 로컬 `master` 순서로 자동 해석됩니다.
  </Step>

  <Step title="워크트리 경로 확인 또는 변경">
    **워크트리 경로**에는 기본값이 자동으로 채워집니다. 저장소 부모 폴더의 형제 디렉터리 형태(`<저장소부모>/<저장소이름>-<브랜치>`)로 제안되며, 브랜치 이름을 바꾸면 경로 기본값도 따라 갱신됩니다(경로를 직접 편집하기 전까지). 브랜치 이름의 `/`는 경로에서 `-`로 바뀌므로, `feature/login`은 `<저장소이름>-feature-login` 폴더가 됩니다.

    폴더 위치를 바꾸고 싶다면 **찾아보기…** 버튼으로 부모 폴더를 직접 고를 수 있습니다.
  </Step>

  <Step title="생성">
    **생성**을 누르면 진행 → 완료 토스트가 뜨고, 새로 만든 워크트리가 자동으로 선택(활성화)됩니다. 그래프와 저장소 개요도 새 워크트리 기준으로 새로고침됩니다.
  </Step>
</Steps>

<Note>
  기준으로 삼을 기본 브랜치를 찾지 못하면(main/master/`origin/HEAD` 모두 없음) 다이얼로그가 이를 안내하고 생성을 막습니다.
</Note>

<Warning>
  경로가 이미 존재해 비어 있지 않거나, 브랜치 이름이 중복·무효이면 Git이 생성을 거부하고 실패 토스트로 사유가 표시됩니다. 이럴 때는 다른 경로나 브랜치 이름으로 다시 시도하세요.
</Warning>

## 워크트리 전환하기

<Steps>
  <Step title="워크트리 행 클릭">
    좌측 사이드바에서 저장소 아래에 나열된 워크트리 행을 클릭하면 그 워크트리로 전환됩니다. 다른 저장소의 워크트리를 고르면 그것이 곧 저장소 전환이기도 합니다.
  </Step>

  <Step title="탭이 히스토리 하나로 초기화됨">
    **실제로 다른 워크트리로 바뀔 때**, 열려 있던 diff 탭들은 모두 닫히고 탭이 그래프를 보여 주는 **히스토리(History)** 탭 하나로 초기화됩니다. 이전 워크트리의 맥락과 맞지 않는 stale 탭이 남지 않도록 하기 위함입니다. 같은 워크트리를 다시 클릭한 경우에는 탭이 그대로 유지됩니다.

    <Frame>
      <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/worktree-switched.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=c52dde323f95d070a5e939057a1b5c13" alt="다른 워크트리로 전환한 직후의 화면. 탭 줄에 히스토리 탭 하나만 남아 있고 사이드바에서는 새로 선택된 워크트리 행이 강조되어 있다" width="2906" height="1784" data-path="images/worktree-switched.png" />
    </Frame>
  </Step>
</Steps>

<Tip>
  히스토리 탭은 항상 첫 자리에 고정돼 있어 닫을 수 없습니다. 그래프·저장소 개요·워킹 카피(Working copy) 상태는 워크트리별로 캐시되므로, 워크트리를 오가도 각 워크트리의 그래프가 빠르게 다시 나타납니다. 자세한 내용은 [워크트리별 상태](/worktrees/status)를 참고하세요.
</Tip>

## 워크트리 삭제하기

<Steps>
  <Step title="삭제 버튼 열기">
    사이드바에서 **연결된 워크트리 행**에 마우스를 올리면 앞섬/뒤처짐 카운터 자리에 휴지통 아이콘(삭제 버튼)이 나타납니다. 클릭하면 삭제 확인 다이얼로그가 열립니다.
  </Step>

  <Step title="옵션 확인">
    다이얼로그에는 "`<경로>` 워크트리를 삭제합니다."라는 안내가 뜨고, 그 아래 두 개의 토글이 있습니다.

    * **브랜치도 함께 삭제(Also delete branch)** (기본 꺼짐): 라벨에 대상 브랜치 이름이 함께 표시됩니다. 워크트리에 체크아웃돼 있던 브랜치까지 삭제하며, 강제 삭제가 켜져 있으면 병합 여부와 무관하게(`git branch -D`) 브랜치를 지우고 꺼져 있으면(`-d`) 병합되지 않은 브랜치는 삭제가 거부됩니다. 분리된 HEAD 워크트리에는 지울 브랜치가 없으므로 이 토글이 나타나지 않습니다.
    * **강제 삭제(Force delete)** (기본 꺼짐): 라벨에 "커밋되지 않은 변경 폐기"라는 부연이 붙습니다. 커밋하지 않은 변경사항이 있는 워크트리도 제거합니다.

    <Frame>
      <img src="https://mintcdn.com/railgit/1HhHpeGsA-i8McQ3/images/worktree-delete-dialog.png?fit=max&auto=format&n=1HhHpeGsA-i8McQ3&q=85&s=c80bbfec85506c03cac05ae0d5c34446" alt="워크트리 삭제 확인 다이얼로그. 삭제할 워크트리 경로 안내 아래에 브랜치도 함께 삭제 토글과 강제 삭제 토글이 차례로 놓여 있고 둘 다 꺼져 있다" width="886" height="496" data-path="images/worktree-delete-dialog.png" />
    </Frame>

    <Note>
      **잠긴(locked) 워크트리**는 강제 삭제 토글만으로는 제거되지 않습니다. Git이 별도의 잠금 무시 절차를 요구하기 때문이며, 아래 [잠긴 워크트리 삭제 실패와 재시도](#잠긴-워크트리-삭제-실패와-재시도)에서 다룹니다.
    </Note>
  </Step>

  <Step title="삭제 실행">
    **삭제**를 누르면 진행 → 완료 토스트로 결과가 표시됩니다. 삭제한 워크트리가 현재 선택 중이었다면 선택은 기본 워크트리로 이동합니다.
  </Step>
</Steps>

<Warning>
  기본 워크트리(primary worktree)에는 삭제 버튼이 나타나지 않습니다. Git이 기본 워크트리 제거를 거부하기 때문입니다.

  또한 강제 삭제를 켜면 그 워크트리 폴더의 **커밋하지 않은 변경사항이 사라집니다.** 되돌릴 수 없으니 신중히 사용하세요.
</Warning>

<Note>
  워크트리는 지워졌지만 브랜치 삭제만 실패한 경우(예: 병합되지 않음)에는 경고 토스트로 부분 실패를 알려 줍니다.
</Note>

### 잠긴 워크트리 삭제 실패와 재시도

삭제가 실패했을 때 ParalleLane은 **한 단계씩만** 위험을 높입니다. 실패 토스트에 재시도 버튼이 붙는 경우는 딱 하나뿐입니다.

<Steps>
  <Step title="1단계 — 강제 삭제 꺼짐: 안내만, 버튼 없음">
    강제 삭제를 끈 채로 삭제하다 실패하면 실패 토스트에는 **액션 버튼이 붙지 않습니다.** 커밋하지 않은 변경 때문이든 잠금 때문이든 마찬가지입니다.

    커밋하지 않은 변경 때문이라면 "커밋되지 않은 변경이 있어 삭제할 수 없습니다. '강제 삭제' 옵션으로 다시 시도하세요"라는 안내가, 잠긴 워크트리라면 "워크트리가 잠겨 있어 삭제할 수 없습니다"라는 안내가 표시됩니다(두 안내 모두 뒤에 Git이 낸 원본 메시지가 이어 붙습니다). 어느 쪽이든 다음 단계로 넘어가려면 **다이얼로그를 다시 열어 강제 삭제 토글을 직접 켜야** 합니다. 안전한 일반 삭제가 원클릭으로 강제 삭제로 승격되는 일은 없습니다.
  </Step>

  <Step title="2단계 — 강제 삭제 켜짐이 잠금에 막히면: '잠금 무시하고 삭제' 버튼">
    강제 삭제를 켜고 재시도했는데 그 워크트리가 잠겨 있어 또 실패하면, "워크트리가 잠겨 있어 삭제할 수 없습니다" 안내 뒤에 이어 붙는 **Git의 원본 에러 메시지**에 잠금 사유(lock reason) 텍스트가 들어 있습니다. 누가·어떤 세션이 그 워크트리를 잠갔는지 여기서 직접 확인할 수 있습니다.

    이때만 토스트에 **잠금 무시하고 삭제** 액션 버튼이 나타납니다. 누르면 모달 없이 곧바로 잠금을 무시하는 삭제로 재시도합니다.

    잠금이 아닌 다른 이유로 강제 삭제가 실패했다면 버튼은 나타나지 않습니다. 잠금 무시로는 해결되지 않는 실패이기 때문입니다.
  </Step>

  <Step title="3단계 — 잠금 무시도 실패하면: 더 이상 버튼 없음">
    잠금 무시하고 삭제까지 실패하면 실패 토스트에 재시도 버튼이 더는 붙지 않습니다. 같은 명령을 무한히 반복하지 않도록 여기서 에스컬레이션이 끝납니다. 남은 원인은 에러 메시지를 보고 직접 해결해야 합니다.
  </Step>
</Steps>

<Warning>
  워크트리 잠금은 보통 **다른 도구나 세션이 그 워크트리를 점유하는 동안 걸어 두는 보호 장치**입니다. ParalleLane은 잠금이 이미 끝난 세션의 잔재인지, 지금 살아 있는 작업의 잠금인지 자동으로 판별하지 않습니다. 그래서 판단 근거로 원본 잠금 사유를 그대로 보여 줍니다.

  **잠금 무시하고 삭제**를 누르기 전에 에러 메시지의 잠금 사유를 꼭 읽어 보세요. 살아 있는 다른 작업 공간을 통째로 날려 버릴 수 있습니다.
</Warning>