⚡
★ 86.6k

Chương 8: Git Worktrees & Quản Lý Branch

Phát triển tính năng hiện đại đòi hỏi sự cách ly. Bạn cần làm việc trên một tính năng mới mà không làm mất ổn định trạng thái làm việc hiện tại, chuyển đổi context mà không cần stash công việc đang dang dở, và chạy các luồng công việc song song mà không cần chuyển branch liên tục. Git worktrees giải quyết tất cả những điều này.

Git Worktrees Là Gì?

Một git worktree cho phép bạn checkout nhiều branch của cùng một repository đồng thời — mỗi branch trong thư mục riêng trên đĩa.

Không có worktrees, repository duy nhất của bạn có một thư mục làm việc. Chuyển branch thay đổi tất cả các file trong thư mục đó. Bạn phải stash các thay đổi, commit công việc đang thực hiện, hoặc có nguy cơ mất trạng thái mỗi khi bạn chuyển đổi context.

Với worktrees, bạn có thể có:

  • ~/projects/myapp/ trên branch main
  • ~/projects/myapp-feature-auth/ trên branch feature/auth
  • ~/projects/myapp-hotfix-123/ trên branch hotfix/issue-123

Tất cả ba là cùng một repository. Các commit, tag, và lịch sử được chia sẻ. Nhưng mỗi thư mục có cây làm việc và staging area riêng, hoàn toàn cách ly nhau.

Đây là nền tảng của chính sách cách ly worktree bắt buộc của Superpowers được giới thiệu trong v4.2.0: mỗi feature branch có worktree riêng, và main branch không bao giờ được sửa đổi trực tiếp.

Tạo Một Branch Phát Triển Mới

Làm theo năm bước này khi bắt đầu công việc mới.

Bước 1: Chọn Thư Mục

Đặt tên thư mục worktree để khớp với tên branch. Giữ nó liền kề với thư mục làm việc chính của bạn:

# Repo chính ở:
/Users/you/projects/myapp

# Worktree mới sẽ ở:
/Users/you/projects/myapp--feature-user-auth

Quy ước hai gạch ngang (--) phân tách trực quan tên dự án khỏi tên branch và giúp dễ nhận diện các worktree bằng ls.

Bước 2: Tạo Branch và Worktree

# Từ bên trong thư mục repo chính:
git worktree add ../myapp--feature-user-auth -b feature/user-auth

# Lệnh này tạo:
# 1. Một branch mới có tên feature/user-auth
# 2. Một thư mục mới tại ../myapp--feature-user-auth
# 3. Thư mục đó được checkout sang branch mới

Để tạo một worktree từ một branch hiện có:

git worktree add ../myapp--feature-user-auth feature/user-auth

Bước 3: Xác Minh An Toàn

Trước khi làm bất kỳ công việc nào, hãy xác minh worktree được thiết lập đúng cách:

cd ../myapp--feature-user-auth

# Xác minh bạn đang ở trên branch đúng
git branch --show-current
# Mong đợi: feature/user-auth

# Xác minh worktree sạch sẽ
git status
# Mong đợi: nothing to commit, working tree clean

# Xác minh bạn đã phân nhánh từ đúng chỗ
git log --oneline -5
# Nên hiển thị lịch sử branch main gần đây làm base

Đừng bỏ qua bước này. Bắt đầu công việc trong branch sai hoặc trên một tree không sạch là nguồn phổ biến của các bug khó hiểu.

Bước 4: Thiết Lập Dự Án

Một số dự án yêu cầu thiết lập bổ sung sau khi checkout mới. Trong worktree mới của bạn:

# Cài đặt dependencies (nếu node_modules không được chia sẻ)
npm install

# Sao chép các file môi trường nếu cần
cp ../myapp/.env.local .env.local

# Tạo bất kỳ file được yêu cầu nào
npm run generate

Kiểm tra CLAUDE.md hoặc README.md của dự án để biết các bước thiết lập chuẩn.

Bước 5: Chạy Test Baseline

Trước khi viết một dòng code tính năng nào, hãy chạy toàn bộ bộ test:

npm test

Tất cả test phải đạt trước khi bạn bắt đầu. Nếu test thất bại trên một checkout sạch, bạn có một vấn đề đã tồn tại từ trước phải được giải quyết trước khi công việc tính năng của bạn bắt đầu. Baseline này đảm bảo rằng bất kỳ lỗi test nào được đưa ra trong công việc của bạn đều do các thay đổi của bạn gây ra, không phải thừa hưởng từ branch base.

Kết Thúc Một Branch Phát Triển

Khi tính năng của bạn hoàn chỉnh và tất cả test đạt, bạn có bốn lựa chọn để xử lý công việc.

Bốn Lựa Chọn

Lựa ChọnKhi Nào Sử DụngĐiều Gì Xảy Ra
Merge Cục BộThay đổi nhỏ, bạn có quyền truy cập ghi, không cần reviewBranch được merge vào main, worktree được xóa
Tạo PRDự án nhóm, cần review, hoặc CI gates phải đạtPR được mở trên remote, worktree được giữ cho đến khi PR merge
Giữ NguyênCông việc đang thực hiện, chưa sẵn sàng merge, có thể quay lại sauWorktree và branch được giữ nguyên, không có hành động
Hủy BỏThử nghiệm thất bại, công việc không còn cần thiếtBranch và worktree bị xóa vĩnh viễn

Lựa Chọn A: Merge Cục Bộ

# Đảm bảo test đạt
npm test

# Chuyển sang main và merge
cd ../myapp
git checkout main
git pull origin main
git merge --no-ff feature/user-auth -m "feat: add user authentication"

# Xóa worktree
git worktree remove ../myapp--feature-user-auth

# Xóa branch
git branch -d feature/user-auth

Lựa Chọn B: Tạo Pull Request

# Push branch lên remote
cd ../myapp--feature-user-auth
git push -u origin feature/user-auth

# Tạo PR (sử dụng GitHub CLI)
gh pr create --title "feat: add user authentication" --body "..."

# Worktree vẫn hoạt động cho đến khi PR được review và merge

Lựa Chọn C: Giữ Nguyên

Không cần hành động. Worktree và branch tồn tại. Ghi lại trạng thái công việc đang thực hiện trong một comment hoặc issue để nó không bị quên.

Lựa Chọn D: Hủy Bỏ

Cảnh báo: Điều này là vĩnh viễn và không thể hoàn tác.

Lựa chọn hủy bỏ yêu cầu xác nhận rõ ràng. Bạn phải gõ từ "discard" khi được nhắc. Điều này ngăn việc vô tình xóa công việc.

# Xóa thư mục worktree
git worktree remove --force ../myapp--feature-user-auth

# Xóa branch cục bộ
git branch -D feature/user-auth

# Nếu đã push lên remote, xóa branch remote cũng vậy
git push origin --delete feature/user-auth

Chỉ hủy bỏ khi bạn chắc chắn công việc không có giá trị. Nếu có bất kỳ nghi ngờ nào, hãy sử dụng "Giữ Nguyên" và xem lại sau.

Quản Lý Nhiều Worktrees

Để xem tất cả các worktree đang hoạt động cho một repository:

git worktree list

Ví dụ output:

/Users/you/projects/myapp              abc1234 [main]
/Users/you/projects/myapp--feature-auth  def5678 [feature/user-auth]
/Users/you/projects/myapp--hotfix-99   ghi9012 [hotfix/issue-99]

Để prune các tham chiếu worktree cũ (sau khi xóa thư mục thủ công):

git worktree prune

Bảo Vệ Main Branch

Giao thức Superpowers thực thi một quy tắc tuyệt đối về main branch:

Không bao giờ commit trực tiếp vào main. Mọi thay đổi đều đi qua một branch và worktree.

Điều này được thực thi bởi chính sách cách ly worktree bắt buộc v4.2.0. Ngay cả những sửa chữa nhỏ, "nhanh chóng" cũng nên sử dụng worktree. Kỷ luật luôn làm việc trong sự cách ly ngăn chặn một loạt vấn đề: các commit vô tình vào main, các thay đổi hỗn hợp trong một branch duy nhất, và mất khả năng hoàn nguyên sạch sẽ.

Nếu bạn thấy mình sắp commit trực tiếp vào main, hãy dừng lại. Tạo một worktree. Nó mất 30 giây và ngăn những sai lầm có thể mất hàng giờ để gỡ rối.