작업 트리

Orca이 모든 기능이나 버그를 자체 Git 작업 트리로 바꾸는 방법입니다.

Orca은 작업 트리 기반입니다. 한 번의 체크아웃으로 분기하고 보관하는 대신 모든 작업은 git worktree를 통해 저장소의 자체 디스크 복사본을 가져옵니다. 이것이 병렬 에이전트를 안전하게 만드는 이유입니다. 즉, 서로의 파일을 밟지 않습니다.

모델

각 저장소에는 **base ref(기본 참조)**가 있으며, 일반적으로 origin/main입니다.
각 작업 트리에는 분기 기준인 **start-from ref(시작 참조)**가 있습니다.
각 작업 트리에는 자체 브랜치, 디스크의 자체 파일 및 자체 에이전트 터미널이 있습니다.
작업 트리를 삭제하면 디렉터리와 브랜치가 모두 제거됩니다(확인 필요). 병합되지 않은 커밋이 있을 수 있어 Git이 로컬 브랜치를 유지하면 Orca가 검토 단계를 제공할 수 있습니다. 보존된 브랜치를 참조합니다.

기능별 수명주기

Create(생성) — 작업 이름, 시작 기준 선택기, 선택적 GitHub / Linear / Jira / GitLab 링크를 지정합니다.
Work(작업) — 에이전트 터미널, 편집기 탭, 브라우저 탭 및 터미널 창이 모두 이 작업 트리로 범위가 제한됩니다.
Review(검토) — 시작 기준 ref와 비교한 diff 보기, Annotate AI Diff(AI Diff 주석), Attribution(기여 내역)을 사용합니다.
Ship(배포) — 커밋, 푸시, PR 열기 및 검사 대기를 모두 인라인으로 수행합니다.
Archive or delete(보관 또는 삭제) — 한 번의 클릭으로 작업 트리와 브랜치를 제거합니다.

생성은 백그라운드에서 실행됩니다.

작업 트리 만들기 대화 상자를 제출하면 즉시 닫힙니다. Orca을 계속 사용하는 동안 git fetch 및 git worktree add 작업은 백그라운드에서 계속됩니다. 새 작업 트리가 진행률 행과 함께 사이드바에 나타나고 작업 트리 탭에는 체크아웃이 완료되어 터미널로 전환될 때까지 실시간 설정 상태가 표시됩니다. 생성이 진행되는 동안 다른 작업 트리로 전환하거나, 진행 상황을 확인하거나, 탭 내 패널에서 취소할 수 있습니다. 생성에 실패하면 패널에서 재시도를 통해 오류를 표시합니다.

선택기에서 시작

작업 트리를 생성할 때 분기할 대상을 선택합니다. 이는 다음과 같습니다.

저장소의 기본 참조(빠른 경로).
또 다른 로컬 브랜치 - 검토 중인 PR 위에 작업을 쌓는 데 유용합니다.
특정 커밋 SHA.
기존 원격 지점 — Orca이 이를 가져와서 확인합니다.

공유 디렉터리와 Git에서 무시하는 파일

새 작업 트리는 깨끗한 체크아웃입니다. Git에서 무시하는 경로에 있는 의존성, 캐시 및 로컬 비밀 값은 다시 만들기 전까지 존재하지 않습니다.

Orca는 다음 세 가지 상호 보완적인 방식으로 이 공백을 채웁니다.

Worktree Shared Paths(작업 트리 공유 경로)(저장소별, Settings(설정) → Repository(저장소)) — 기본 체크아웃의 경로를 각 새 작업 트리에 생성합니다. 가능한 경우 macOS에서는 APFS 복제 복사를 사용하고, 그 외에는 심볼릭 링크를 사용합니다.
worktree.sharedDirectories의 orca.yaml — 같은 방식으로 공유할 Git에서 무시하는 디렉터리의 저장소 커밋 목록입니다(복사가 아니라 symlink/share). node_modules 또는 .cache처럼 크고 다시 빌드할 수 있는 트리에 사용합니다. 항목은 기본 체크아웃에 디렉터리로 존재하고 동시에 Git에서 무시되어야 하며, 추적 중이거나 없는 경로는 건너뜁니다.
저장소 루트의 .worktreeinclude — 각 새 작업 트리에 심볼릭 링크가 아닌 복사본으로 넣을 Git에서 무시하는 파일 또는 디렉터리 목록이며, 각 작업 트리가 자체 복사본을 소유합니다. 일반적인 항목으로 .env, .vscode/ 아래의 로컬 구성이 있습니다. 빈 줄과 # 주석을 허용합니다. 현재는 리터럴 경로만 지원하며 글로브와 부정 패턴은 경고와 함께 건너뜁니다. 추적 중이거나 없거나 Git에서 무시되지 않는 경로는 복사하지 않습니다.

orca.yaml 공유 디렉터리는 사용자별 Worktree Shared Paths(작업 트리 공유 경로) 목록에 추가되며, 이를 대체하지 않습니다. 이미 shared/linked된 경로는 .worktreeinclude에서 다시 복사하지 않습니다.

# orca.yaml (repo root)
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude (repo root)
.env
.env.local
.vscode/settings.json

생성 대화 상자: 프로젝트, 실행 위치, 에이전트 및 작업 링크

Create Workspace(작업 공간 생성) 대화 상자는 **Project(프로젝트)**와 **Run on(실행 위치)**에 자동 완성 콤보 상자를 사용합니다.

입력하여 필터링하고 Enter(Enter 키)를 누르면 선택된 행을 확정합니다.
**Project(프로젝트)**는 **Add a new project(새 프로젝트 추가)**를 항상 맨 아래에 고정합니다. 아직 프로젝트가 없는 설치 환경에서도 생성 흐름이 막히지 않습니다.
**Run on(실행 위치)**에는 준비된 호스트와 레시피뿐 아니라 해당 시스템에서 프로젝트 설정이 아직 필요한 호스트도 표시됩니다. 설정이 필요한 호스트에서는 생성 양식을 벗어나지 않고 **Set project location(프로젝트 위치 설정)**을 선택한 다음 기존 checkout/folder를 찾아 선택하거나 Git 저장소를 해당 호스트에 복제합니다. Orca는 새로 준비된 위치를 선택하므로 작업 트리 생성을 계속할 수 있습니다. 연결이 끊긴 SSH/원격 호스트에는 실행 대상으로 선택하지 않고 Connect(연결) 옵션을 제공할 수 있습니다. **Add host(호스트 추가)**는 SSH 또는 Remote Orca Server 대상에 대해 계속 고정됩니다.
Agent(에이전트) 선택기는 접힌 상태나 펼친 상태에서 생성 시 선택한 에이전트를 **Set as default(기본값으로 설정)**할 수 있으며 Blank Terminal(빈 터미널)도 포함합니다.
이름 필드에서 GitHub PR, Linear 이슈, GitLab MR 또는 Jira(Jira) 이슈를 연결합니다. Jira URL을 붙여 넣거나 Jira(Jira) 모드에서 검색할 수 있습니다. 연결된 이슈는 작업 트리 카드에 표시됩니다. Jira 항목 서랍을 참조합니다.

Orca 실행 방식을 참조합니다.

이모지가 포함된 작업 공간 이름

작업 공간 이름 필드에 Slack 형식의 단축 코드(:rocket:)를 입력하고 단축 코드 제안 팝오버에서 선택할 수 있습니다. 작업 트리를 두 번 클릭하여 이름을 바꾸거나, **Edit Worktree Details(작업 트리 세부 정보 편집)**에서 편집하거나, Worktree Jump Palette(작업 트리 점프 팔레트)(Cmd-J)에 단축 코드를 입력할 때도 동일한 선택기를 사용할 수 있습니다. 표시 이름에는 이모지가 유지됩니다. Orca가 Git 브랜치 이름을 만들 때는 알려진 이모지를 읽을 수 있는 단축 코드로 다시 씁니다(예: 🚀 → rocket). 점프 팔레트 검색은 이 단축 코드에서 파생된 부분으로 이모지 이름의 작업 공간을 찾습니다.

지점 이름 지정

기본적으로 Orca은 사용자가 입력한 작업공간 이름이나 연결된 GitHub PR, Linear/Jira 문제 또는 작업공간이 생성될 때 GitLab MR에서 새 작업 트리의 분기 이름을 파생합니다. 대신 명시적인 분기 이름을 설정하려면 Create Worktree(작업 트리 만들기) 대화 상자에서 Advanced(고급) 서랍을 확장하고 Branch name(브랜치 이름) 필드(자리 표시자 feature/my-branch)에 입력하세요.

같은 서랍에서 새 작업 공간의 **Parent workspace(상위 작업 공간)**로 동일한 저장소의 활성 작업 트리를 선택할 수 있습니다. 이는 Orca의 사이드바에서 작업 공간을 중첩할 뿐 Git 기록이나 브랜치는 변경하지 않습니다. Orca는 보관된 작업 공간과 순환 구조를 만드는 선택 항목을 제외합니다.

Linear 이슈에서 만들면 Orca는 이슈 제목만 슬러그로 변환하지 않고 Linear가 해당 이슈에 지정한 브랜치 이름을 사용합니다. Linear가 브랜치 이름을 제공하는 경우 이를 브랜치 재정의 값으로 사용하며, 이는 Linear가 UI에서 제안하는 이름과 같습니다.

Branch name(브랜치 이름) 필드는 입력한 작업 공간 이름이나 기준 브랜치에서 만들 때만 제공됩니다. 작업 공간이 추적 중인 작업 항목에 연결되면 브랜치는 해당 항목에서 파생됩니다. 연결된 GitHub PR은 제출 시 브랜치를 다시 확인하기도 하므로, Orca는 조용히 무시되는 재정의를 방지하기 위해 필드를 숨깁니다.

사이드바 레이아웃

사이드바는 기본적으로 project(프로젝트)별로 작업 트리를 그룹화합니다. 최상위 행은 프로젝트(프로젝트 1개 = git repo 1개 또는 관련 클러스터)이며 현재 작업 중인 작업 트리로 확장됩니다. 헤더에는 자체 필터 입력(전역 검색과 별개)이 있으므로 사이드바를 떠나지 않고도 목록 범위를 좁힐 수 있습니다.

사이드바 헤더의 필터 메뉴는 호스트와 프로젝트 범위를 공통 Show(표시) 섹션 아래에 묶습니다. 이 섹션에는 Hosts(호스트) 및 프로젝트를 위한 하위 메뉴 행이 있으며, 그 뒤에 숨김 토글이 표시됩니다.

Sleeping(절전 중) 작업 공간 — 이 필터에서도 각 프로젝트의 entry-point / main(진입점/기본) 작업 공간이 계속 표시되어 해당 체크아웃이 유휴 상태일 때 프로젝트 행이 사라지지 않습니다.
Except default branch(기본 브랜치 제외)(**Hide sleeping(절전 중인 항목 숨기기)**이 켜진 동안만) — 절전 중인 항목을 정리할 때 기본 브랜치 작업 공간을 계속 표시합니다. 절전 중인 작업 공간이 이미 표시되는 경우 이 하위 옵션은 숨겨집니다.
Default branch(기본 브랜치) 작업 공간(기본 체크아웃 행)
Automation-created(자동화에서 생성됨) 작업 공간
CLI-created(CLI에서 생성됨) 작업 공간 — orca worktree create을 통해 생성됩니다(카드에 마우스를 올리면 Orca CLI(Orca CLI) 출처 세부 정보가 표시됩니다).
Other-client(다른 클라이언트) 작업 공간 — 공유 원격 Orca 서버에 다른 페어링 클라이언트가 만든 작업 공간이 있으면 **Hide other-client workspaces(다른 클라이언트의 작업 공간 숨기기)**가 표시됩니다. 이 옵션을 켜면 이 기기의 목록에는 여기서 만든 작업 공간만 유지됩니다. 빈 Cmd-J 최근 항목과 숫자 단축키에도 동일한 필터가 적용되지만, 검색어를 입력하면 숨겨진 행도 계속 찾습니다.
Detached HEAD(분리된 HEAD) 작업 공간 — 브랜치가 아닌 커밋에 있는 체크아웃

활성 필터 수가 필터 컨트롤에 표시되며 **Clear(지우기)**는 켜져 있는 필터만 초기화합니다. 텍스트 검색과 작업 트리 점프 팔레트(Cmd-J)에서는 검색어를 입력하면 이 필터로만 숨겨진 작업 공간도 계속 찾을 수 있습니다. 점프 팔레트에는 **Tab(Tab 키)**으로 여는 자체 host/project 필터도 있습니다.

여러 Git 저장소가 들어 있는 상위 폴더를 추가하면 Orca는 선택한 저장소를 각각 가져오거나 하나의 프로젝트 그룹 아래에 묶을 수 있습니다.

사이드바 위쪽의 Search(검색) 버튼은 작업 트리 점프 팔레트(Cmd-J)를 엽니다. 키보드 탐색을 주로 사용하지 않는 사용자가 클릭으로 열 수 있는 동일한 화면입니다. 상태 표시줄에는 에이전트 활동이 인라인으로 표시되며, 읽지 않은 작업 트리는 배지 대신 굵게 표시됩니다.

장기 작업을 계속 표시하려면 작업 트리를 프로젝트 맨 위에 고정할 수 있으며, 작업 트리를 마우스 오른쪽 버튼으로 클릭하면 보관/절전/삭제 작업이 표시됩니다. 키보드로 삭제를 시작하려면 작업 트리 또는 폴더 작업 공간에 마우스를 올리고 macOS에서는 Cmd-Shift-Backspace, Windows/Linux에서는 Ctrl-Shift-Backspace를 누릅니다. 일반 확인 대화 상자는 계속 표시됩니다. 클릭할 때 Cmd을 누릅니다(Ctrl는 Linux/Windows에서 사용합니다). 그러면 작업 트리가 다중 선택에 추가됩니다. Shift를 누르면 연속 범위를 선택합니다. 선택된 작업 트리 중 하나를 마우스 오른쪽 버튼으로 클릭하면 선택한 모든 작업 트리에 작업이 적용됩니다. 저장소 행 자체는 드래그하여 순서를 바꿀 수 있습니다.

작업 트리에 중첩된 하위 작업 트리가 있으면(예: 오케스트레이션 또는 상위 항목을 지정한 worktree create으로 생성한 경우) 컨텍스트 메뉴에 Sleep with Descendants (N)(하위 항목과 함께 절전(N)) 및 **Delete with Descendants…(하위 항목과 함께 삭제…)**가 표시될 수 있습니다. 하위 항목과 함께 절전하면 선택한 작업 공간과 동일한 프로젝트, 저장소 및 호스트에 속하며 검증된 모든 중첩 하위 항목의 활성 패널을 닫습니다. 활성 터미널이나 브라우저 탭이 있는 작업 공간만 절전 대상이 됩니다. 하위 항목과 함께 삭제는 기존 연쇄 삭제 동작을 명시적으로 제공합니다. 오래된 계보 링크, 순환 및 호스트나 저장소 경계를 넘는 하위 항목은 제외됩니다.

사이드바에서 작업 트리 제목을 두 번 클릭하면 인라인으로 이름을 변경할 수 있습니다. 카드의 다른 위치를 두 번 클릭하면 기존처럼 전체 편집 대화 상자가 열립니다. **Edit Worktree Details(작업 트리 세부 정보 편집)**에서 이슈 필드는 GitHub 또는 Linear를 허용합니다(필드의 칩을 사용하며 URL을 붙여넣으면 자동으로 감지합니다). 작업 공간마다 하나의 이슈만 연결할 수 있으며, 공급자를 변경하거나 필드를 지우면 이전 연결이 해제됩니다. 호스트 연결이 끊긴 SSH 작업 공간에서는 카드 제목 행에 인라인 재연결 컨트롤이 표시될 수 있습니다(SSH 작업 트리 참조).

사용자가 작업 공간 이름을 직접 바꾸면 Orca는 작업 트리의 브랜치가 변경되어도 해당 표시 이름을 유지합니다. 사용자 지정 이름을 지우면 브랜치에서 자동으로 이름을 만드는 동작을 다시 시작합니다. Orca가 생성한 이름은 계속 브랜치를 따릅니다.

`Resource Manager`(리소스 관리자) 정리

제거하기 전에 사용 환경 전반의 작업 공간을 검토해야 할 때 **Resource Manager → Clean up workspaces(리소스 관리자 → 작업 공간 정리)**를 사용합니다. 목록에는 로컬 작업 트리, 메인 작업 트리, 폴더 작업 공간 및 연결이 끊긴 SSH 호스트의 작업 공간이 포함됩니다. 제거할 항목을 선택하기 전에 목록을 검색하거나 필터링하거나 정렬하여 각 작업 공간의 상태, 최근 활동, 크기, Git 상태 및 연결된 리뷰를 확인합니다.

보존된 브랜치

작업 공간을 일괄 삭제하면(사이드바 다중 선택 또는 Resource Manager(리소스 관리자) 정리) 디스크의 폴더는 그대로 제거됩니다. 병합되지 않은 커밋이 있을 수 있어 Git이 로컬 브랜치 삭제를 거부하면 Orca가 해당 브랜치를 유지하고 **Review N Branches(N개 브랜치 검토)**와 같은 토스트를 표시합니다. 토스트를 열면 유지된 브랜치 목록이 표시되어 일부는 강제로 삭제하고 나머지는 남겨 둘 수 있습니다. 선택하지 않은 브랜치는 저장소에 남으며 작업 공간 폴더는 복원되지 않습니다.

다중 저장소 프로젝트 그룹 및 폴더 작업공간

여러 Git 저장소가 포함된 상위 폴더를 가져오면 Orca은 해당 저장소를 사이드바의 단일 project group(프로젝트 그룹) 아래에 그룹화할 수 있습니다. 각 프로젝트 그룹은 상위 폴더 수준에 있는 작업 트리와 유사한 항목인 folder workspace(폴더 작업 공간) 흐름을 노출하고 해당 작업 소스를 아래 저장소 중 하나에 바인딩하므로 작업 공간 자체가 사이드바에서 형제 항목과 그룹화되어 있어도 한 기능의 GitHub/GitLab/Linear/Jira 작업 표면이 올바른 저장소에 연결된 상태로 유지됩니다.

작업 공간을 만들려면 사이드바에서 프로젝트 그룹의 헤더 행에 마우스를 놓고 + 작업을 클릭하세요(도구 설명: “그룹에 대한 작업 공간 만들기”). 작성기 대화 상자(“폴더 작업 공간 만들기”)에서는 작업 공간의 작업 소스에 대한 소스 프로젝트를 선택하고, 작업 공간 이름을 지정하고, 선택적으로 링크된 이슈 또는 PR을 첨부하도록 요청합니다. 제출하면 폴더 작업공간이 일반 저장소 범위 작업 트리와 함께 프로젝트 그룹 아래에 나타납니다.

프로젝트 그룹을 삭제할 때 Orca은 동일한 작업으로 그룹에 포함된 프로젝트(기본 저장소 등록)를 제거할 수 있는 확인란도 제공합니다. 따라서 더 이상 사용되지 않는 클러스터를 정리하면 여러 번 확인하는 것이 아니라 한 번 확인하는 것입니다.

일반 Git 사용

모든 Orca 작업 트리는 실제 Git 작업 트리입니다. 터미널을 열고 git status, git rebase, git cherry-pick 등을 사용할 수 있습니다. Orca는 다음 렌더링 변경 사항을 선택합니다.

git worktree add로 직접 만든 작업 트리는 Orca에 표시하도록 설정하기 전까지 외부 작업 트리로 유지됩니다. 저장소에서 이를 숨기면 사이드바에 hidden worktrees(숨겨진 작업 트리) 카드가 표시됩니다. 이 카드를 클릭해 **Non-Orca worktrees(Orca 외부 작업 트리)**를 연 다음, 사이드바에 표시할 작업 트리에서 **Show(표시)**를 선택합니다.

**Settings(설정) → General(일반) → Workspace(작업 공간)**에서 외부 작업 트리 소스의 전역 기본값을 설정합니다. 여기에는 Claude Code 작업 트리, GSD 작업 트리, 기타 위치 및 사용자가 추가한 사용자 지정 절대 경로 위치가 포함됩니다. 이러한 기본값은 해당 호스트의 현재 작업 트리와 앞으로 생성할 작업 트리에 적용되며, 새 전역 사용자 지정 루트는 처음에는 숨겨집니다. 프로젝트의 Non-Orca worktrees(Orca 외부 작업 트리) 대화 상자에서는 해당 프로젝트의 소스 설정을 재정의하거나 전역 설정으로 되돌린 다음, 개별 숨겨진 작업 트리를 검색하고 복구할 수 있습니다.

CLI에서 git worktree remove을 실행하면 Orca는 다음에 해당 저장소를 새로 고칠 때 자체 상태를 확인하고 정리합니다.