Git worktree: hai nhiệm vụ trong hai thư mục làm việc

Bạn đang cùng Claude Code xây dựng một danh sách locale và đã làm được nửa phần tìm kiếm. Đúng lúc đó, bạn phát hiện phiên bản trang đã lưu có chú thích dưới tiêu đề không chính xác. Sửa chỉ mất hai phút, nhưng bạn muốn kiểm tra riêng thay vì trộn vào phần tìm kiếm còn dang dở.

Hãy xem cách dành cho nhiệm vụ thứ hai một thư mục làm việc riêng trong cùng repository, mở một phiên Claude Code riêng ở đó và cuối cùng lưu kết quả mà không nhầm lẫn. Chỉ thêm thư mục thứ hai thì không làm công việc nhanh hơn. Mục đích duy nhất là giữ cho hai nhiệm vụ không trộn lẫn trong cùng một bộ tệp.

Khi một thư mục làm việc là chưa đủ

Dự án thực hành locale-guide là một trang trình duyệt liệt kê các locale. Hiện tại, nhiệm vụ A đang được thực hiện trong thư mục đó: tìm kiếm, branch feature/search và một thay đổi chưa hoàn tất:

git status --short
 M app.js

Không thể để mất thay đổi này, nhưng cũng chưa thể xem nó là kết quả hoàn chỉnh. Lúc này xuất hiện nhiệm vụ B, hoàn toàn không liên quan đến tìm kiếm: sửa chú thích trong index.html ở phiên bản đã lưu trong main.

Ý nghĩ đầu tiên có thể là mở terminal thứ hai rồi chạy thêm một claude trong cùng thư mục. Hai phiên trò chuyện riêng, nhưng dùng chung tệp. Nếu cả hai agent cùng sửa một khu vực, các thay đổi có thể bị trộn lẫn. Trong ví dụ đơn giản này, chú thích và phần tìm kiếm vẫn nằm ở hai tệp khác nhau, nhưng cả hai phiên đều thấy cùng một dự án còn dang dở. Chuyển branch cũng đòi hỏi bạn xử lý các thay đổi hiện tại trước.

Giải pháp là dành cho nhiệm vụ B một không gian làm việc riêng. Git có worktree: một thư mục làm việc riêng của cùng repository. Claude Code có flag --worktree, flag này chuẩn bị thư mục như vậy rồi khởi chạy phiên ngay tại đó. Trước hết ta xem cơ chế, sau đó là flag.

Một repository, nhiều thư mục làm việc, mỗi thư mục có branch riêng. Tên trong hình chỉ là ví dụ; bài viết này dùng hai thư mục làm việc và ba branch: main, feature/search và fix/label.

Lưu ý ngay từ đầu: đây không phải cách làm bắt buộc cho mọi nhiệm vụ. Nếu working tree sạch và thay đổi nhỏ, thư mục thứ hai chỉ khiến bạn thêm việc. Luân phiên xử lý các nhiệm vụ trong cùng một thư mục cũng hoàn toàn ổn.

Branch, thư mục làm việc và phiên

Ba khái niệm này dễ bị nhầm lẫn vì bạn thường làm việc với chúng cùng lúc:

Vậy là đã rõ câu trả lời cho câu hỏi về terminal thứ hai: phiên mới tách riêng cuộc trò chuyện, chứ không tách các tệp. Muốn tách tệp, bạn cần một thư mục làm việc thứ hai.

Lịch sử và các branch được dùng chung vì cả hai thư mục gắn với cùng một repository. Cài đặt Git cũng được dùng chung theo mặc định, dù Git hỗ trợ cài đặt riêng cho từng worktree. Nhưng tệp đang làm và thay đổi đã đưa vào staging thì mỗi thư mục có bộ riêng. Phần tìm kiếm chưa commit ở thư mục đầu sẽ không tự xuất hiện ở thư mục thứ hai.

Thông thường, bạn không thể checkout cùng một branch ở hai thư mục cùng lúc. Git sẽ từ chối và cho biết thư mục đang sử dụng branch đó:

fatal: 'fix/label' is already used by worktree at '/projects/locale-guide-label'

Chọn trạng thái ban đầu

Trong ví dụ thực hành, repository đã được tạo, có ít nhất một commit, branch cục bộ main và branch feature/search. Hiện cả hai cùng trỏ đến một commit, còn phần tìm kiếm mới chỉ là thay đổi chưa commit. Hãy xem trạng thái ban đầu bằng ba lệnh trong thư mục chính:

git status --short        # các thay đổi chưa được lưu
git branch --show-current # branch hiện tại của thư mục chính
git log -1 --oneline main # commit mới nhất trong main

 M app.js
feature/search
d5ec405 add locale guide page

Để sửa chú thích độc lập, ta chọn main: nhiệm vụ B cần phiên bản trang đã lưu, không phải trạng thái hiện tại của phần tìm kiếm. Lưu ý đây là branch main cục bộ trên máy bạn. Nó không nhất thiết trùng với branch cùng tên trên repository từ xa, và lệnh này không tải gì từ mạng về.

Nếu nhiệm vụ thứ hai cần kết quả của nhiệm vụ thứ nhất, trước tiên hãy xác định commit đã lưu nào cần dùng rồi tạo thư mục từ commit đó. Lệnh git worktree add thông thường không tự chuyển các thay đổi chưa commit sang thư mục mới. Sao chép tệp riêng hoặc dùng thêm công cụ chuẩn bị môi trường là những thao tác khác.

Tạo thư mục làm việc thứ hai

Từ thư mục locale-guide:

git worktree add -b fix/label ../locale-guide-label main

Đọc từ trái sang phải: tạo branch mới fix/label, đặt thư mục làm việc bên cạnh theo đường dẫn ../locale-guide-label và lấy main làm điểm xuất phát. Đối số cuối cùng chỉ rõ base. Nếu bỏ nó, Git sẽ dùng commit HEAD hiện tại của branch feature/search, nhưng không lấy các thay đổi chưa commit. Trong ví dụ này, hai branch vẫn ở cùng một commit nên các tệp sẽ giống nhau; sau khi có commit cho phần tìm kiếm, lựa chọn base sẽ ảnh hưởng đến kết quả. Git phản hồi đại khái như sau:

Preparing worktree (new branch 'fix/label')
HEAD is now at d5ec405 add locale guide page

Tiếp theo, hãy kiểm tra kết quả. Flag -C yêu cầu Git chạy lệnh trong thư mục được chỉ định mà không cần chuyển vào đó:

git worktree list
git -C ../locale-guide-label branch --show-current
git -C ../locale-guide-label status --short

Đầu ra mẫu với các đường dẫn giả định; trên máy bạn, chúng sẽ khác:

/projects/locale-guide        d5ec405 [feature/search]
/projects/locale-guide-label  d5ec405 [fix/label]

fix/label

Danh sách hiển thị cả hai thư mục cùng branch tương ứng. Thư mục chính vẫn ở branch feature/search với phần tìm kiếm chưa xong; thư mục mới dùng fix/label. Lệnh status trong thư mục thứ hai không in gì cả - thư mục sạch, đúng như mục tiêu của ta.

Nếu không thể dùng đường dẫn hoặc tên branch, Git sẽ từ chối và giải thích lý do, chẳng hạn already exists hoặc is already used by worktree. Hãy kiểm tra danh sách worktree, các branch và nội dung thư mục đã chỉ định. Có thể đó là thư mục còn lại từ lần chạy trước hoặc thuộc một nhiệm vụ khác. Đừng thêm --force một cách tùy tiện: trước tiên hãy tìm hiểu những gì đang tồn tại và xem chúng có cần thiết không.

Mở nhiệm vụ thứ hai trong Claude Code

Mở locale-guide-label trong cửa sổ IDE riêng, hoặc chuyển đến đó trong terminal mới rồi chạy claude. Phiên mới không biết gì về nhiệm vụ A, điều đó hoàn toàn bình thường - nó chỉ cần ngữ cảnh của riêng mình:

Thư mục dự kiến: locale-guide-label, branch: fix/label.
Trước tiên, hãy kiểm tra thư mục và branch thực tế. Nếu khác, hãy dừng lại.
Đọc index.html.
Thay chú thích dưới tiêu đề bằng "Danh sách locale: mã, ngôn ngữ và quốc gia".
Không thay đổi gì khác trong tệp và cho tôi xem thay đổi.

Sau khi sửa, hãy kiểm tra git status và git diff trong cả hai terminal: ở thư mục thứ hai chỉ có chú thích thay đổi trong index.html, còn thay đổi trước đó trong app.js vẫn ở thư mục đầu. Chỉ xem status thì biết tên tệp thay đổi, chứ không chứng minh nội dung của chúng còn nguyên. Để so sánh chính xác, hãy tạm dừng phần tìm kiếm trong lúc kiểm tra. Kiểm tra thư mục chính từ terminal của chính nó; đừng yêu cầu agent trong phiên tách biệt chuyển sang đó. Hãy mở trang từ thư mục thứ hai, nếu không bạn sẽ thấy chú thích cũ.

Còn có một lối tắt. Lệnh claude --worktree label-fix tự tạo thư mục làm việc và khởi chạy phiên ở đó. Theo tài liệu hiện tại, thư mục được tạo bên trong repository tại .claude/worktrees/label-fix/, branch mang tên worktree-label-fix, còn điểm xuất phát là branch mặc định trên repository từ xa (thường là main), không phải commit hiện tại của bạn. Nếu chưa cấu hình repository từ xa, nó dùng commit cục bộ hiện tại. Vì vậy cách này khác với việc chỉ rõ main trong lệnh ở trên, dù trong dự án đơn giản kết quả thường giống nhau. Có thể thay đổi mặc định này trong cài đặt; hãy kiểm tra chi tiết theo tài liệu của phiên bản bạn đang dùng.

Flag này tiện khi bạn đồng ý với base mặc định và muốn nhanh chóng dành chỗ riêng cho một nhiệm vụ. Nếu đã tạo thư mục bằng lệnh ở trên thì không cần chạy thêm flag này, vì như vậy sẽ có thêm một thư mục nữa. Bạn cũng nên thêm .claude/worktrees/ vào .gitignore, nếu không nội dung các thư mục mới sẽ xuất hiện trong thư mục chính dưới dạng tệp chưa được theo dõi.

Những gì vẫn được dùng chung

Thư mục riêng tách biệt ít thứ hơn bạn tưởng lúc đầu:

Cột thứ ba là điều dễ bị quên nhất. Worktree chỉ tách các tệp của Git, chứ không cô lập cả máy tính. Hai máy chủ cục bộ không thể cùng dùng một cổng, và yêu cầu từ cả hai thư mục sẽ đến cùng một cơ sở dữ liệu bên ngoài nếu cấu hình như vậy. Các bước kiểm tra Claude Code thực hiện khi làm việc trong thư mục riêng cũng không biến nó thành sandbox cho toàn hệ thống.

Thư mục thứ hai nhận các tệp từ commit đã chọn. Nếu dependency và cài đặt cục bộ không được lưu trong Git, thông thường bạn cần chuẩn bị môi trường riêng; các công cụ bổ sung có thể tự động hóa việc đó. Đừng sao chép .env một cách máy móc: cùng thông tin xác thực có thể khiến cả hai lần chạy kết nối đến cùng một dịch vụ. Với danh sách tĩnh của ta, không cần máy chủ hay secret nào - trang chỉ cần mở như một tệp.

Lưu và chuyển kết quả

Trong thư mục B, hãy kiểm tra chú thích trên trình duyệt, xem git diff rồi commit đúng tệp cần thiết:

git add index.html
git diff --cached
git commit -m "fix: correct locale list label"

Trước khi commit, hãy chắc chắn rằng chỉ thay đổi cần thiết được đưa vào staging. Nếu git diff --cached hiển thị thay đổi khác, hãy xử lý chúng trước.

Commit đã vào repository dùng chung và bạn có thể thấy nó từ thư mục chính. Nhưng nó chưa tự động xuất hiện trong main hay feature/search: commit vẫn nằm trong branch riêng, chờ bạn quyết định có merge hay không.

Chỉ nên chuyển kết quả khi nhiệm vụ A đã hoàn thành hoặc ít nhất đã được lưu, đồng thời thư mục chính sạch. Đừng chuyển sang main giữa lúc phần tìm kiếm còn dang dở - hãy xử lý nó trước. Khi thư mục chính đã sạch:

git checkout main
git merge fix/label

Fast-forward
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Đầu ra này tương ứng với trường hợp main không thay đổi kể từ khi tạo fix/label. Nếu Git báo xung đột, hãy dừng lại và xử lý theo quy trình merge - đây là chủ đề riêng, được trình bày trong bài viết "Branch và merge trong Git". Sau khi merge, hãy mở lại trang: chú thích phải được cập nhật, còn danh sách locale vẫn như cũ. Branch feature/search không được cập nhật theo; trước khi tiếp tục tìm kiếm, hãy cân nhắc riêng xem có cần đưa thay đổi từ main vào branch này không.

Xóa thư mục không còn cần thiết

Trước tiên, hãy đóng phiên trong thư mục thứ hai và mọi thứ bạn đã chạy ở đó. Sau đó kiểm tra xem còn thứ gì cần giữ lại không:

git -C ../locale-guide-label status --short --ignored

Các tệp đã sửa và tệp mới sẽ hiện ngay; flag --ignored hiển thị các tệp bị bỏ qua - thường chính là nơi lưu cài đặt cục bộ và ghi chú. Sau khi xác nhận kết quả đã được lưu vào đúng branch, hãy xóa thư mục từ thư mục chính:

git worktree remove ../locale-guide-label
git worktree list

Nếu có tệp được theo dõi đã sửa hoặc tệp mới không bị bỏ qua, Git thường từ chối xóa thư mục:

fatal: '../locale-guide-label' contains modified or untracked files, use --force to delete it

Đừng vội làm theo gợi ý trong thông báo. Hãy kiểm tra tệp và lưu những gì cần giữ. Sau khi xóa, Git có thể không khôi phục được dữ liệu chưa commit. Cũng đừng dựa vào việc Git từ chối như một biện pháp bảo vệ hoàn toàn: tệp bị bỏ qua vẫn có thể bị xóa mà không cần --force, đó là lý do ta kiểm tra riêng chúng.

Còn một chi tiết dễ nhầm. Lệnh Git xóa thư mục làm việc nhưng không xóa branch - fix/label vẫn còn trong danh sách git branch. Điều đó tiện vì kết quả vẫn còn nguyên. Khi branch thực sự không còn cần thiết và mọi thứ cần dùng đã được merge, hãy xóa branch bằng một thao tác riêng.

Đừng xóa thư mục ngoài Git bằng trình quản lý tệp: repository vẫn nghĩ thư mục còn tồn tại và danh sách worktree sẽ giữ một mục trỏ đến thư mục đã mất.

Cách thực hiện nhiệm vụ thứ hai trong Claude Code

Toàn bộ quy trình gói gọn trong sáu bước:

1. tách riêng nhiệm vụ thứ hai khỏi nhiệm vụ đầu và xác định trạng thái đã lưu nào sẽ làm điểm xuất phát;
2. tạo thư mục làm việc với base được chỉ định rõ, hoặc chạy claude --worktree nếu mặc định phù hợp với bạn;
3. kiểm tra đường dẫn và branch trong thư mục mới trước khi sửa bất cứ thứ gì;
4. cung cấp cho phiên ngữ cảnh chỉ liên quan đến nhiệm vụ này, không kèm lịch sử của nhiệm vụ kia;
5. kiểm tra thay đổi ngay tại nơi bạn thực hiện và commit kết quả;
6. quyết định việc merge, rồi mới xóa thư mục.

Thư mục riêng không kiểm tra code và cũng không duyệt công việc thay bạn. Nó chỉ cho mỗi nhiệm vụ bộ tệp làm việc riêng. Ví dụ cho thấy lợi ích của cách này: chú thích được sửa và kiểm tra riêng, còn phần tìm kiếm dang dở vẫn ở thư mục đầu.

Tự kiểm tra

Thư mục thứ hai không có phần tìm kiếm chưa commit. Có gì sai không?
Không, đó là chủ ý. Thư mục được tạo từ commit trong main, không phải từ các tệp hiện tại của nhiệm vụ A. Thay đổi chưa commit vẫn nằm trong thư mục riêng.

Hai phiên mở trong cùng một thư mục. Các nhiệm vụ đã tách biệt chưa?
Cuộc trò chuyện riêng, nhưng các tệp vẫn dùng chung. Thay đổi có thể bị trộn lẫn nếu hai nhiệm vụ sửa cùng khu vực.

Đã commit trong branch B, nhưng chú thích chưa xuất hiện trong main.
Đó là điều bình thường: commit vẫn nằm trong branch riêng. Nó không thay đổi branch khác; muốn vậy thì cần merge.

Máy chủ cục bộ thứ hai không chạy được trên cùng cổng.
Thư mục riêng không tách các cổng. Hãy chạy trên một cổng khác.

Git từ chối xóa thư mục làm việc.
Hãy đọc lý do bị từ chối: ngoài các tệp chưa lưu, thư mục có thể đang bị khóa hoặc chính là thư mục làm việc chính. Lưu những gì cần giữ và tìm hiểu trạng thái hiện tại. Đừng thêm --force một cách tùy tiện.

Nếu muốn tự thực hành, hãy dùng một repository thực hành riêng có vài commit: tạo hai thư mục, chỉ sửa văn bản trong thư mục thứ hai, kiểm tra cả hai rồi xóa thư mục thừa. Bạn không cần dịch vụ hay tài khoản nào.