using-git-worktrees

Tổng quan

using-git-worktrees là gì?

using-git-worktrees là một kỹ năng workflow từ repository obra/superpowers, hướng dẫn bạn tạo các Git worktree tách biệt để phát triển tính năng. Nó chuẩn hóa cách và nơi tạo worktree, để bạn có thể làm việc song song trên nhiều branch mà không phải liên tục chuyển branch trong cùng một thư mục làm việc.

Thay vì phải tự đoán nơi đặt worktree hoặc mạo hiểm với các thư mục chưa được track/ignore, kỹ năng này mã hóa một quy trình rõ ràng để chọn và kiểm tra thư mục. Mục tiêu là đảm bảo môi trường triển khai được cô lập một cách tin cậy trong khi cây dự án chính của bạn vẫn sạch sẽ.

Kỹ năng này dành cho ai?

Kỹ năng này được thiết kế cho các lập trình viên:

• Làm việc song song trên nhiều tính năng hoặc bản sửa bug
• Muốn có một quy ước Git worktree có thể lặp lại trên nhiều dự án
• Cần yên tâm rằng thư mục worktree được đặt đúng chỗ và không làm bẩn các commit
• Dùng Git trên dòng lệnh và thoải mái với việc chạy các lệnh shell đơn giản

Đặc biệt phù hợp với các team muốn có một workflow Git được ghi chép rõ ràng, nhất quán và một cách an toàn hơn để tạo nhanh môi trường tính năng tạm thời hoặc kéo dài.

using-git-worktrees giải quyết vấn đề gì?

using-git-worktrees giúp bạn tránh các vấn đề phổ biến khi làm việc với nhiều branch:

• Chi phí chuyển branch: Làm việc trên nhiều branch cùng lúc mà không phải liên tục stash và checkout.
• Thư mục gốc dự án bừa bộn: Tránh việc rải rác các thư mục tạm và thư mục worktree khắp nơi.
• Commit nhầm thư mục worktree: Luồng làm việc nhấn mạnh việc kiểm tra xem thư mục worktree cục bộ đã được ignore trước khi tạo.
• Quy ước không nhất quán giữa các máy: Bằng cách kiểm tra các thư mục hiện có và tùy chọn cấu hình trong CLAUDE.md, kỹ năng này hướng bạn tới một layout chuẩn cho từng dự án.

Nếu bạn thường xuyên dùng Git worktree hoặc muốn bắt đầu dùng chúng một cách an toàn, kỹ năng này mang đến một quy trình gọn nhẹ nhưng có định hướng rõ ràng.

Khi nào using-git-worktrees là lựa chọn phù hợp?

Bạn nên dùng using-git-worktrees khi:

• Bạn sắp bắt đầu một tính năng cần tách biệt khỏi workspace hiện tại.
• Bạn chuẩn bị triển khai dựa trên một thiết kế/kế hoạch sẵn có và muốn một worktree sạch để thực hiện.
• Repository của bạn đã dùng thư mục .worktrees hoặc worktrees và bạn muốn tiếp tục theo quy ước đó.

Kỹ năng này có thể bớt hữu ích nếu:

• Bạn luôn chỉ làm việc trên một branch tại một thời điểm và không cần nhiều working copy.
• Bạn đã có một công cụ nội bộ nghiêm ngặt, tự động quản lý worktree theo cách khác.

Trong hầu hết trường hợp còn lại, áp dụng luồng using-git-worktrees có thể giúp workflow Git của bạn dễ đoán hơn và an toàn hơn.

Cách sử dụng

Cài đặt và thiết lập

Để thêm kỹ năng using-git-worktrees vào môi trường của bạn, hãy cài từ repository obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Sau khi cài đặt:

1. Mở file skills/using-git-worktrees/SKILL.md trong bản checkout của repository.
2. Đọc toàn bộ một lần để nắm rõ các bước chọn thư mục và kiểm tra an toàn.
3. Đảm bảo bạn đang làm việc bên trong một Git repository mà bạn sẵn sàng tạo thêm các thư mục worktree.

Bạn không cần thêm phụ thuộc nào ngoài Git và một shell có thể chạy các lệnh được nêu trong mô tả kỹ năng.

Quy trình cốt lõi: bắt đầu công việc tính năng trong workspace tách biệt

Khi bạn bắt đầu làm một tính năng mới và muốn một workspace tách biệt, hãy làm theo luồng tổng quát mà using-git-worktrees mã hóa:

1. Thông báo workflow (cho chính bạn và bất kỳ trợ lý/công cụ nào):

   "I'm using the using-git-worktrees skill to set up an isolated workspace."

2. Xác định thư mục worktree bằng quy trình chọn thư mục (xem phần tiếp theo). Điều này giúp tránh việc đặt worktree ở những đường dẫn ngẫu nhiên.

3. Chạy bước kiểm tra an toàn tương ứng với loại thư mục đã chọn (cục bộ theo dự án hay global). Bước này rất quan trọng để tránh commit nhầm các thư mục worktree.

4. Tạo Git worktree cho branch bạn cần. Ví dụ:

   git worktree add <path-to-worktree> <branch-name>
   

5. Chuyển sang worktree mới và thực hiện phần triển khai ở đó, giữ cho bản working copy ban đầu sạch sẽ, sẵn sàng cho code review, sửa lỗi nhanh hoặc các tác vụ khác.

Lặp lại luồng này bất cứ khi nào bạn bắt đầu một tính năng, spike, hoặc thử nghiệm mới cần tách biệt khỏi thư mục làm việc hiện tại.

Quy trình chọn thư mục

using-git-worktrees định nghĩa một thứ tự chọn thư mục có cấu trúc để bạn luôn biết worktree nên nằm ở đâu và không phải quyết định lại mỗi lần.

1. Ưu tiên các thư mục worktree đã tồn tại

Từ thư mục gốc của repository, kiểm tra các thư mục worktree ưu tiên theo thứ tự:

ls -d .worktrees 2>/dev/null     # Ưu tiên (ẩn)
ls -d worktrees 2>/dev/null      # Thay thế

• Nếu .worktrees tồn tại, hãy dùng nó.
• Nếu không có .worktrees nhưng có worktrees, hãy dùng worktrees.
• Nếu cả hai đều không tồn tại, chuyển sang bước tiếp theo.

Quy tắc này giúp workflow của bạn nhất quán với các lựa chọn trước đó trong cùng dự án.

2. Kiểm tra CLAUDE.md để tìm tùy chọn của dự án

Nếu không có thư mục worktree chuẩn, hãy tìm một tùy chọn được ghi lại trong CLAUDE.md ở gốc dự án:

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

Nếu CLAUDE.md nêu rõ một quy ước thư mục worktree, hãy dùng nó mà không cần hỏi thêm. Điều này cho phép dự án tập trung ghi lại layout worktree ưu tiên của mình.

3. Hỏi và chọn vị trí mới khi chưa có quy ước

Nếu không có thư mục sẵn và không có tùy chọn ghi trong CLAUDE.md, hãy chủ động chọn nơi các worktree mới sẽ được đặt. Kỹ năng này gợi ý bạn (hoặc team) tự đặt một lựa chọn rõ ràng:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

• Tùy chọn 1: .worktrees/ giữ worktree nằm cạnh dự án, mặc định ẩn và dễ tìm ngay trong repo.
• Tùy chọn 2: ~/.config/superpowers/worktrees/<project-name>/ gom worktree của từng dự án vào một nơi bên ngoài thư mục gốc repo, hữu ích nếu bạn muốn thư mục Git chính trông tối giản hơn.

Sau khi chọn một phương án, hãy tiếp tục dùng vị trí đó cho cùng dự án để tránh phân tán.

Kiểm tra an toàn trước khi tạo worktree

Kỹ năng using-git-worktrees đặc biệt nhấn mạnh các bước kiểm tra an toàn, nhất là khi dùng thư mục cục bộ trong dự án nằm bên trong Git repository.

Xác minh thư mục cục bộ đã được ignore

Với các thư mục cục bộ như .worktrees hoặc worktrees, hãy xác minh rằng chúng đã được Git ignore trước khi bạn tạo worktree bên trong. Kỹ năng này coi đây là điều kiện MUST.

Tối thiểu, bạn nên:

• Xác nhận rằng .worktrees hoặc worktrees xuất hiện trong một file ignore phù hợp (.gitignore, .git/info/exclude, hoặc file ignore global), và
• Dùng git check-ignore để đảm bảo Git thực sự ignore thư mục đó trong cấu hình hiện tại.

Mẫu kiểm tra điển hình là chạy git check-ignore với đường dẫn thư mục và xác nhận Git đang coi nó là bị ignore, bao gồm cả cấu hình ignore local, global và system.

Nếu thư mục chưa được ignore:

• Thêm nó vào file ignore thích hợp, commit rule ignore nếu nó thuộc về repository, và
• Chạy lại kiểm tra trước khi tạo bất kỳ worktree nào ở vị trí đó.

Điều này giảm rủi ro việc hạ tầng worktree của bạn bị stage hoặc commit nhầm.

Dùng vị trí global một cách an toàn

Nếu bạn chọn dùng thư mục global (ví dụ dưới ~/.config/superpowers/worktrees/), các thư mục này nằm ngoài repository và không bị Git track. Khi đó, yêu cầu ignore không còn quá quan trọng, nhưng bạn vẫn nên đảm bảo:

• Đường dẫn ổn định giữa các máy (hoặc được ghi lại cho đồng đội).
• Bạn có đủ dung lượng đĩa cho nhiều worktree đầy đủ.

Liên tục áp dụng các bước kiểm tra này giúp lịch sử Git của bạn tập trung vào thay đổi mã nguồn, không phải artifact của công cụ.

Điều chỉnh kỹ năng cho workflow của bạn

Kỹ năng using-git-worktrees được thiết kế có chủ đích là gọn nhẹ và tập trung vào từng repository. Để tích hợp vào workflow rộng hơn của bạn:

• Ghi lại lựa chọn cuối cùng về thư mục worktree trong tài liệu đóng góp hoặc onboarding của dự án.
• Cân nhắc thêm một đoạn ngắn vào CLAUDE.md mô tả cách team của bạn sử dụng Git worktree.
• Gói các bước chọn thư mục và kiểm tra vào script shell riêng nếu bạn muốn một lệnh duy nhất để thiết lập, nhưng vẫn coi các quy tắc gốc là nguồn tham chiếu chuẩn.

Kỹ năng này được xem là một "reference implementation" rõ ràng mà bạn có thể dùng nguyên trạng hoặc điều chỉnh cẩn trọng cho phù hợp với môi trường của mình.

Câu hỏi thường gặp (FAQ)

Lợi ích chính của using-git-worktrees so với checkout Git thông thường là gì?

using-git-worktrees giúp bạn làm việc dễ dàng trên nhiều branch song song bằng cách tạo thêm các thư mục làm việc (worktree) cùng chia sẻ lịch sử Git. Thay vì liên tục checkout và stash trong một thư mục duy nhất, bạn giữ mỗi tính năng hoặc bản sửa ở một workspace tách biệt, được dẫn dắt bởi quy trình chọn thư mục và kiểm tra an toàn nhất quán.

Tôi cài đặt kỹ năng using-git-worktrees như thế nào?

Cài kỹ năng từ repository obra/superpowers bằng lệnh:

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

Sau khi cài, mở skills/using-git-worktrees/SKILL.md trong bản checkout local để làm theo workflow chi tiết.

Tôi có cần thay đổi toàn bộ workflow Git hiện tại để dùng kỹ năng này không?

Bạn không cần phải thay đổi toàn bộ workflow. using-git-worktrees tập trung vào cách bạn khởi tạo và quản lý các workspace tách biệt. Bạn vẫn có thể commit, rebase và push như bình thường; kỹ năng này chủ yếu chuẩn hóa nơi và cách bạn tạo worktree, đồng thời đảm bảo chúng được đặt ở vị trí an toàn.

Tôi có thể dùng using-git-worktrees với bất kỳ Git repository nào không?

Có, miễn là repository đó tương thích với Git worktree nói chung. Kỹ năng này dựa trên các lệnh Git tiêu chuẩn và tiện ích shell. Để có kết quả tốt nhất, hãy chạy các bước kiểm tra thư mục từ gốc repository và làm theo khuyến nghị về ignore với mọi thư mục worktree cục bộ.

Nếu dự án của tôi đã có quy ước worktree khác thì sao?

Nếu dự án của bạn đã dùng .worktrees, worktrees, hoặc một quy ước được ghi trong CLAUDE.md, using-git-worktrees sẽ tự động bắt được tùy chọn đó thông qua các quy tắc chọn thư mục. Nếu quy ước của bạn hoàn toàn khác, bạn vẫn có thể áp dụng các nguyên tắc (chọn thư mục rõ ràng và kiểm tra an toàn) nhưng trỏ chúng tới layout thư mục sẵn có của dự án.

using-git-worktrees có phù hợp với các dự án lớn hoặc dài hạn không?

Có. Kỹ năng này đặc biệt hữu ích với các dự án lớn nơi có nhiều branch dài hạn. Quy trình chọn thư mục có cấu trúc và nhấn mạnh vào rule ignore giúp repository của bạn vẫn gọn gàng theo thời gian, ngay cả khi bạn tích lũy nhiều worktree cho các công việc đang diễn ra.

Khi nào tôi nên tránh dùng using-git-worktrees?

Bạn có thể không cần đến kỹ năng này nếu hiếm khi làm việc trên nhiều hơn một branch cùng lúc, hoặc nếu team của bạn đã dùng một công cụ chuyên dụng khác để quản lý worktree và công cụ đó đã áp đặt quy ước thư mục riêng. Trong các trường hợp đó, cấu trúc bổ sung từ using-git-worktrees có thể không mang lại đủ lợi ích để bạn thay đổi thói quen.

Tôi có thể xem định nghĩa gốc của kỹ năng này ở đâu?

Định nghĩa chuẩn (authoritative) của using-git-worktrees nằm trong file SKILL.md bên trong thư mục skills/using-git-worktrees của repository obra/superpowers trên GitHub. Hãy tham khảo file đó để có mô tả hành vi chính xác và cập nhật nhất.