Worktree trong Orca

Orca được xây dựng theo hướng worktree-native. Thay vì branch và stash trên một checkout duy nhất, mỗi task có một bản copy riêng của repo trên đĩa thông qua git worktree. Đây chính là điều giúp việc chạy nhiều agent song song trở nên an toàn - chúng không bao giờ giẫm lên file của nhau.

Mô hình hoạt động

• Mỗi repo có một base ref (thường là origin/main).
• Mỗi worktree có một start-from ref - ref mà nó branch ra từ đó.
• Mỗi worktree có branch riêng, file riêng trên đĩa, và terminal agent riêng.
• Xóa một worktree sẽ xóa cả thư mục lẫn branch (có xác nhận trước). Nếu git giữ lại local branch vì có thể còn commit chưa merge, Orca sẽ đưa ra một bước review - xem phần Branch được giữ lại.

Vòng đời của mỗi feature

1. Tạo - đặt tên task, chọn start-from, tuỳ chọn liên kết GitHub / Linear / Jira / GitLab.
2. Làm việc - terminal agent, tab editor, tab trình duyệt, pane terminal - tất cả đều gắn với worktree này.
3. Review - diff view so với start-from ref, Annotate AI Diff, Attribution.
4. Ship - commit, push, mở PR, chờ check - tất cả làm ngay trong app.
5. Archive hoặc xóa - một click là xóa cả worktree lẫn branch.

Việc tạo worktree chạy nền

Khi bạn submit dialog Create Worktree, dialog đóng lại ngay lập tức - git fetch và git worktree add vẫn tiếp tục chạy nền trong khi bạn tiếp tục dùng Orca. Worktree mới xuất hiện trên sidebar với một dòng tiến trình, và tab của worktree hiển thị trạng thái setup trực tiếp cho tới khi checkout xong và chuyển sang terminal. Bạn có thể chuyển sang worktree khác trong lúc tạo đang chạy, theo dõi tiến trình, hoặc hủy ngay từ panel trong tab. Nếu việc tạo thất bại, panel sẽ hiển thị lỗi kèm nút Retry.

Chọn start-from

Khi tạo worktree, bạn chọn nó sẽ branch từ đâu. Có thể là:

• Base ref của repo (đường nhanh nhất).
• Một local branch khác - hữu ích khi muốn xếp chồng công việc lên trên một PR đang review.
• Một commit SHA cụ thể.
• Một remote branch có sẵn - Orca sẽ fetch và checkout nó.

Thư mục dùng chung & file gitignore

Một worktree mới toanh là một checkout sạch. Dependency, cache, và secret local nằm trong các path bị gitignore sẽ không có sẵn cho tới khi bạn tạo lại chúng.

Orca lấp khoảng trống này theo ba cách bổ sung lẫn nhau:

1. Worktree Shared Paths (theo từng repo, trong Settings → Repository) - các path này sẽ được vật chất hoá từ checkout chính vào mỗi worktree mới (clone-copy kiểu APFS trên macOS nếu có thể, nếu không thì dùng symlink).
2. worktree.sharedDirectories trong orca.yaml - danh sách các thư mục bị gitignore được check-in vào repo để chia sẻ theo cách tương tự (symlink/share, không copy). Dùng cho các cây thư mục lớn có thể rebuild lại như node_modules hay .cache. Các mục này phải tồn tại như thư mục trong checkout chính và phải bị gitignore; path đã tracked hoặc không tồn tại sẽ bị bỏ qua.
3. .worktreeinclude ở gốc repo - danh sách file hoặc thư mục bị gitignore cần copy (không symlink) vào mỗi worktree mới, để mỗi worktree sở hữu bản copy riêng. Ví dụ thường gặp: .env, config local trong .vscode/. Được phép có dòng trống và comment #. Hiện chỉ hỗ trợ path tường minh - glob và phủ định (negation) sẽ bị bỏ qua kèm cảnh báo. Path đã tracked, không tồn tại, hoặc không bị gitignore sẽ không được copy.

Các thư mục chia sẻ trong orca.yaml sẽ cộng thêm vào danh sách Worktree Shared Paths theo từng user, chứ không thay thế nó. Các path đã được share/link rồi thì sẽ không bị copy lại từ .worktreeinclude.

# orca.yaml (gốc repo)
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude (gốc repo)
.env
.env.local
.vscode/settings.json

Dialog Create: Project, Run on, agent, và task link

Dialog Create Workspace dùng combobox kiểu type-ahead cho Project và Run on:

• Gõ để lọc; Enter chọn dòng đang được highlight.
• Project luôn giữ mục Add a new project ghim ở cuối - việc tạo không bao giờ bế tắc kể cả khi install chưa có project nào.
• Run on liệt kê các host và recipe đã sẵn sàng, cộng thêm các host còn cần setup project trên máy đó. Các dòng cần setup sẽ hiển thị chi tiết như Project not set up on this host; chúng vẫn hiển thị nhưng chưa chọn được cho tới khi sẵn sàng. Host SSH / remote đang mất kết nối có thể hiển thị nút Connect mà không cần chọn làm run target. Add host luôn ghim sẵn cho target SSH hoặc Remote Orca Server.
• Bộ chọn Agent (thu gọn hoặc mở rộng) có thể Set as default cho agent bạn chọn khi tạo, kể cả Blank Terminal.
• Có thể liên kết một GitHub PR, Linear issue, GitLab MR, hoặc Jira issue ngay từ ô tên (dán URL Jira hoặc tìm kiếm ở chế độ Jira). Issue đã liên kết sẽ hiện trên card worktree. Xem thêm về Jira items drawer trong tài liệu gốc.

Xem thêm trang “Ways to run Orca” trong tài liệu gốc.

Tên workspace bằng emoji

Trong ô tên workspace, bạn có thể gõ shortcode kiểu Slack (:rocket:) và chọn từ popover gợi ý shortcode. Cùng bộ chọn này hoạt động khi bạn double-click để đổi tên worktree, sửa trong Edit Worktree Details, hoặc gõ shortcode trong Worktree Jump Palette (Cmd-J). Tên hiển thị giữ nguyên emoji; khi Orca tự sinh tên git branch, nó sẽ chuyển emoji quen thuộc thành shortcode dễ đọc (ví dụ 🚀 → rocket). Tìm kiếm trong Jump Palette khớp các workspace đặt tên bằng emoji theo đoạn shortcode được suy ra đó.

Đặt tên branch

Mặc định Orca tự suy ra tên branch của worktree mới từ tên workspace bạn gõ, hoặc từ GitHub PR, Linear/Jira issue, GitLab MR đã liên kết khi workspace được tạo từ một trong số đó. Để đặt tên branch tường minh, mở rộng drawer Advanced trong dialog Create Worktree và gõ vào ô Branch name (placeholder feature/my-branch).

Khi tạo từ một Linear issue, Orca dùng chính tên branch mà Linear đề xuất cho issue đó (nếu Linear cung cấp) làm branch override - giống hệt tên mà Linear sẽ gợi ý trong UI của nó - thay vì chỉ slugify tiêu đề issue.

Ô Branch name chỉ xuất hiện khi bạn tạo từ tên workspace tự gõ hoặc từ một base branch. Khi workspace gắn với một work item đã được track, branch sẽ được suy ra từ item đó - một GitHub PR đã liên kết thậm chí còn re-resolve lại branch ngay lúc submit - nên Orca ẩn ô này để tránh trường hợp override bị âm thầm bỏ qua.

Bố cục sidebar

Mặc định sidebar nhóm worktree theo project - các dòng ở cấp cao nhất là project (một project = một git repo hoặc một cụm repo liên quan), mở rộng ra thành các worktree bạn đang thực sự làm việc. Phần header có ô filter riêng (tách biệt với ô tìm kiếm toàn cục) để bạn thu hẹp danh sách mà không cần rời sidebar.

Menu filter ở header sidebar nhóm phạm vi host và project chung dưới mục Show (submenu cho Hosts và các project), sau đó tới các toggle ẩn:

• Workspace Sleeping - workspace entry-point / main của mỗi project vẫn hiển thị dưới filter này để dòng project không biến mất khi checkout đó đang idle.
• Except default branch (chỉ khi Hide sleeping đang bật) - giữ hiển thị các workspace default-branch trong lúc quét sleeping; sub-option này bị ẩn khi sleeping workspace đã hiển thị sẵn.
• Workspace Default branch (dòng checkout chính).
• Workspace tạo bởi automation.
• Workspace tạo bởi CLI - tạo qua orca worktree create (hover vào card để xem chi tiết nguồn gốc Orca CLI).
• Workspace Other-client - Hide other-client workspaces xuất hiện khi một Remote Orca Server dùng chung có workspace được tạo từ một client đã pair khác; bật lên để giữ danh sách trên thiết bị này chỉ gồm workspace bạn tạo tại đây. Danh sách recent trống của Cmd-J và phím tắt số cũng theo cùng filter này; gõ query vẫn tìm ra các dòng bị ẩn.
• Workspace Detached HEAD - checkout đang đứng trên một commit thay vì một branch.

Số filter đang bật hiển thị trên nút filter; Clear chỉ reset các filter đang bật. Tìm kiếm bằng text và Worktree Jump Palette (Cmd-J) vẫn tìm được các workspace chỉ bị ẩn bởi các filter này khi bạn gõ query - jump palette còn có filter host/project riêng (Tab).

Khi bạn thêm một thư mục cha chứa nhiều Git repo, Orca có thể import các repo được chọn riêng lẻ hoặc gộp chúng vào một project group.

Nút Search ở đầu sidebar mở Worktree Jump Palette (Cmd-J) - cùng một giao diện, dùng bằng click cho người không quen điều hướng bằng bàn phím. Status bar hiển thị hoạt động của agent ngay inline; worktree chưa đọc được in đậm thay vì gắn badge.

Bạn có thể ghim (pin) một worktree lên đầu project để giữ công việc chạy dài trong tầm mắt, và right-click một worktree để xem các action archive / sleep / delete. Giữ Cmd (Ctrl trên Linux/Windows) trong khi click để thêm worktree vào multi-selection, hoặc giữ Shift để chọn một dải liên tiếp - right-click bất kỳ worktree nào đang được chọn sẽ áp dụng action cho toàn bộ selection. Các dòng repo có thể kéo để sắp xếp lại thứ tự.

Khi một worktree có worktree con lồng bên trong (ví dụ từ orchestration hoặc worktree create với một parent), context menu còn có thể hiện Sleep with Descendants (N) và Delete with Descendants…. Sleep with descendants đóng các panel đang active trên workspace đã chọn và mọi worktree con hợp lệ trong cùng project, repo, host - chỉ những workspace có terminal hoặc tab trình duyệt đang sống mới bị nhắm để sleep. Delete with descendants làm rõ hành vi cascading delete vốn đã có sẵn. Các liên kết lineage lỗi thời, chu trình vòng lặp, và các con nằm khác host hoặc repo sẽ bị loại trừ.

Double-click vào tiêu đề worktree trên sidebar để đổi tên inline. Double-click ở chỗ khác trên card vẫn mở dialog edit đầy đủ. Trong Edit Worktree Details, ô issue chấp nhận GitHub hoặc Linear (chip trên ô; dán URL để tự nhận diện). Mỗi workspace chỉ liên kết được một issue - đổi provider hoặc xóa ô này sẽ unlink issue trước đó. Với workspace SSH có host đang mất kết nối, dòng tiêu đề trên card có thể hiện control reconnect inline (xem SSH worktrees trong tài liệu gốc).

Dọn dẹp bằng Resource Manager

Dùng Resource Manager → Clean up workspaces khi cần review các workspace trên toàn bộ setup trước khi xóa. Danh sách bao gồm local worktree, main worktree, folder workspace, và workspace trên các host SSH đang mất kết nối. Tìm kiếm, filter, hoặc sắp xếp danh sách để kiểm tra trạng thái, hoạt động gần đây, dung lượng, git state, và review liên kết của từng workspace trước khi chọn xóa.

Branch được giữ lại

Xóa hàng loạt workspace (multi-select trên sidebar hoặc Resource Manager cleanup) vẫn xóa các thư mục trên đĩa. Nếu git từ chối xóa một local branch vì có thể còn commit chưa merge, Orca sẽ giữ lại các branch đó và hiện một toast dạng Review N Branches. Mở nó ra sẽ liệt kê các branch được giữ lại để bạn force-delete một số và giữ lại số khác. Branch không được chọn vẫn nằm trong repository; thư mục workspace không được khôi phục lại.

Project group nhiều repo & folder workspace

Khi bạn import một thư mục cha chứa nhiều Git repo, Orca có thể nhóm các repo đó vào một project group trên sidebar. Mỗi project group có luồng folder workspace - một entry kiểu worktree nằm ở cấp thư mục cha, gắn nguồn task của nó với một trong các repo bên dưới, để bề mặt task GitHub/GitLab/Linear/Jira của một feature vẫn gắn đúng với repo tương ứng dù workspace đó được nhóm chung với các “anh em” của nó trên sidebar.

Để tạo một folder workspace, hover vào dòng header của project group trên sidebar và bấm action + (tooltip: “Create workspace for group”). Dialog composer (“Create Folder Workspace”) sẽ hỏi bạn chọn project nguồn cho task source của workspace, đặt tên, và tùy chọn gắn issue hoặc PR liên kết. Submit xong, folder workspace sẽ xuất hiện dưới project group, cạnh các worktree gắn với từng repo riêng lẻ.

Khi xóa một project group, Orca còn cho một checkbox để xóa luôn các project (đăng ký repo bên dưới) thuộc group đó trong cùng một hành động - nhờ vậy việc dọn dẹp một cụm không còn dùng nữa chỉ cần một lần xác nhận thay vì nhiều lần.

Dùng git thông thường

Mỗi worktree trong Orca là một git worktree thật sự. Bạn có thể mở terminal trong đó và dùng git status, git rebase, git cherry-pick, và bất cứ lệnh git nào khác - Orca sẽ nhận thấy thay đổi ở lần render tiếp theo.

Các worktree bạn tự tạo bằng git worktree add sẽ nằm ngoài cho tới khi bạn cho hiển thị trong Orca. Nếu một repo đang ẩn chúng, sidebar sẽ hiện một card hidden worktrees. Bấm vào đó để mở Non-Orca worktrees, rồi chọn Show cho các worktree bạn muốn đưa vào sidebar.

Trong Non-Orca worktrees, bạn có thể đặt visibility riêng cho worktree của Claude Code, worktree của GSD, các vị trí khác, và bất kỳ vị trí đường dẫn tuyệt đối tuỳ chỉnh nào bạn thêm vào. Các cài đặt nguồn này áp dụng cho cả worktree hiện tại lẫn tương lai; dialog còn cho phép tìm kiếm và khôi phục từng worktree ẩn riêng lẻ.

Nếu bạn chạy git worktree remove từ CLI, Orca sẽ nhận ra và tự dọn state của nó ở lần refresh repo đó tiếp theo.

Nguồn

Dịch và biên soạn từ trang Worktrees trong tài liệu chính thức của Orca ADE (onorca.dev).