Git Worktree vào hệ sinh thái Microservices Bài 3: Các lệnh Git Worktree cốt lõi dành cho Backend Developer

Sau khi đã nắm rõ cơ chế "một nhà kho .git, nhiều không gian làm việc" ở Bài 2, giờ là lúc chúng ta đưa lý thuyết vào thực tế. Trong bài viết này, chúng ta sẽ đi qua toàn bộ vòng đời (Lifecycle) của một Worktree: từ lúc khởi tạo để xử lý tác vụ, kiểm tra trạng thái, bảo vệ dữ liệu cho đến khi dọn dẹp sạch sẽ sau khi code đã được merge.

1. Khởi tạo không gian làm việc mới: git worktree add

Cú pháp cơ bản của lệnh khởi tạo như sau:

Bash

git worktree add <đường-dẫn-thư-mục-mới> <tên-nhánh>

Tuy nhiên, trong thực tế phát triển Microservices, chúng ta thường rơi vào 3 kịch bản chính dưới đây. Giả sử bạn đang đứng ở thư mục gốc payment-service (đang code dở nhánh feature/loyalty-v2):

Kịch bản A: Tạo worktree kèm theo một nhánh hoàn toàn mới (Dùng khi làm Hotfix hoặc Feature mới)

Đột nhiên có bug trên Production. Bạn cần tạo một nhánh hotfix/payment-timeout xuất phát từ nhánh origin/main và đặt nó ở thư mục nằm ngang hàng với thư mục hiện tại:

Bash

# Cờ -b giúp tạo nhánh mới ngay lập tức
# Cú pháp: git worktree add -b <nhánh-mới> <đường-dẫn> <nhánh-gốc>
git worktree add -b hotfix/payment-timeout ../payment-hotfix origin/main

Ngay sau khi gõ lệnh này, một thư mục payment-hotfix sẽ xuất hiện bên ngoài, chứa sẵn toàn bộ source code của origin/main và đã được chuyển sẵn sang nhánh hotfix/payment-timeout. Bạn chỉ việc mở IDE ở thư mục đó và bắt đầu sửa lỗi!

Kịch bản B: Tạo worktree từ một nhánh đã có sẵn trên Remote (Dùng khi Review PR đồng nghiệp)

Đồng nghiệp nhờ bạn chạy thử nhánh feature/refund-flow của họ để kiểm tra luồng hoàn tiền. Thay vì checkout làm hỏng môi trường hiện tại, bạn chỉ cần:

Bash

# Cập nhật danh sách nhánh mới nhất từ remote
git fetch origin

# Tạo worktree trỏ thẳng vào nhánh của đồng nghiệp (không dùng cờ -b)
git worktree add ../payment-review-refund feature/refund-flow

Git sẽ tự động nhận diện nhánh feature/refund-flow trên origin, kéo code về thư mục ../payment-review-refund và thiết lập tracking branch cho bạn.

Kịch bản C: Tạo worktree ở trạng thái Detached HEAD (Thử nghiệm nhanh / So sánh code)

Đôi khi bạn chỉ muốn mở xem lại code của hệ thống ở phiên bản v1.2.0 tháng trước hoặc chạy nhanh một bài load test ở nhánh main mà không có ý định commit code mới. Bạn có thể dùng cờ --detach:

Bash

git worktree add --detach ../payment-test-v1 v1.2.0

2. Kiểm soát toàn bộ không gian làm việc: git worktree list

Khi bạn làm việc với 5-10 Microservices và mỗi service lại tách ra 2-3 worktrees, bạn sẽ cần một câu lệnh để biết chính xác thư mục nào đang chạy nhánh nào.

Bash

git worktree list

Kết quả trả về sẽ rất trực quan:

Plaintext

/Users/dev/workspace/payment-service                a1b2c3d [feature/loyalty-v2]
/Users/dev/workspace/payment-hotfix                 f9e8d7c [hotfix/payment-timeout]
/Users/dev/workspace/payment-review-refund          c4d5e6f [feature/refund-flow]
/Users/dev/workspace/payment-test-v1                88a99b0 (detached HEAD)

Nhìn vào danh sách này, bạn nắm được ngay: Đường dẫn vật lý trên ổ cứng, mã Hash của commit hiện tại, và tên nhánh đang được mở ở từng nơi.

3. Di chuyển và Đổi tên thư mục: git worktree move

Một sai lầm kinh điển của người mới dùng Worktree là sử dụng lệnh mv của hệ điều hành hoặc đổi tên thư mục trực tiếp trên Finder/Explorer.

Như đã học ở Bài 2, thư mục .git gốc lưu đường dẫn tuyệt đối trỏ tới các worktree phụ. Nếu bạn tự ý đổi tên thư mục bằng tay, mối liên kết hai chiều này sẽ bị đứt gãy! Để đổi tên hoặc di chuyển thư mục worktree một cách an toàn, hãy luôn dùng lệnh của Git:

Bash

# Đổi tên hoặc di chuyển thư mục worktree sang vị trí mới
git worktree move ../payment-hotfix ../payment-hotfix-urgent

Lệnh này sẽ di chuyển thư mục vật lý đồng thời tự động cập nhật lại đường dẫn trong file .git/worktrees/.../gitdir.

4. Khóa bảo vệ Worktree quan trọng: git worktree lock

Trong một số trường hợp (ví dụ: bạn lưu worktree trên ổ cứng gắn ngoài, USB, Network Drive, hoặc đơn giản là một worktree đang chứa các cấu hình test cực kỳ quan trọng không được phép xóa nhầm), bạn có thể "khóa" nó lại kèm theo lý do:

Bash

git worktree lock ../payment-hotfix --reason "Đang chạy load test với dữ liệu thật, cấm xóa!"

Khi một worktree đã bị lock, mọi lệnh xóa (remove hay prune) đều sẽ bị từ chối cho đến khi bạn chủ động mở khóa bằng lệnh:

Bash

git worktree unlock ../payment-hotfix

5. Dọn dẹp chiến trường sau khi xong việc: remove và prune

Sau khi bản hotfix/payment-timeout của bạn đã được đẩy lên, tạo Pull Request và Merge thành công vào main, thư mục payment-hotfix đã hoàn thành sứ mệnh. Đừng để nó tồn tại mãi gây rác ổ cứng.

Cách 1: Xóa chuẩn chỉnh bằng git worktree remove (Khuyên dùng)

Chỉ cần chạy lệnh sau từ bất kỳ worktree nào của repo đó:

Bash

git worktree remove ../payment-hotfix

• Lưu ý an toàn: Nếu trong thư mục payment-hotfix vẫn còn file sửa dở chưa commit, Git sẽ báo lỗi và từ chối xóa để bảo vệ công sức của bạn. Nếu bạn chắc chắn muốn xóa bỏ toàn bộ những thay đổi nháp đó, hãy thêm cờ --force: git worktree remove --force ../payment-hotfix.

• Sau khi remove thư mục worktree, nhánh hotfix/payment-timeout vẫn còn tồn tại trong lịch sử Git. Bạn có thể xóa nốt nhánh local này nếu muốn bằng git branch -d hotfix/payment-timeout.

Cách 2: Dọn dẹp "hậu quả" khi lỡ xóa tay bằng git worktree prune

Điều gì xảy ra nếu bạn quên mất lệnh git worktree remove và lỡ tay bấm Shift + Delete (hoặc rm -rf ../payment-hotfix) để xóa thẳng thư mục đó trên ổ cứng?

Lúc này, thư mục code đã biến mất, nhưng thông tin quản lý bên trong .git/worktrees/payment-hotfix vẫn còn tồn tại (biến thành một "worktree ma"). Hệ quả là khi bạn muốn checkout lại nhánh hotfix/payment-timeout ở nơi khác, Git vẫn báo lỗi nhánh này đang bị chiếm dụng!

Để dọn sạch các bản ghi quản lý bị mồ côi do xóa thư mục bằng tay, hãy chạy:

Bash

# Kiểm tra xem có những bản ghi mồ côi nào sẽ bị dọn (Dry-run)
git worktree prune --dry-run

# Thực thi dọn dẹp sạch sẽ
git worktree prune --verbose

6. Bảng Cheat Sheet tổng hợp cho Backend Developer

Bạn có thể lưu lại bảng tóm tắt nhanh dưới đây để tra cứu ngay trong quá trình làm việc hàng ngày:

Mục đích	Câu lệnh chuẩn	Ghi chú thực chiến
Tạo worktree + Nhánh mới	git worktree add -b <nhánh-mới> <đường-dẫn> <nhánh-gốc>	Dùng khi làm Feature mới hoặc Hotfix từ origin/main.
Tạo worktree từ nhánh có sẵn	git worktree add <đường-dẫn> <nhánh-có-sẵn>	Dùng khi kéo nhánh của đồng nghiệp về để Review PR.
Xem danh sách Worktree	git worktree list	Kiểm tra nhanh thư mục nào đang mở nhánh nào.
Di chuyển / Đổi tên thư mục	git worktree move <đường-dẫn-cũ> <đường-dẫn-mới>	Tuyệt đối không dùng lệnh mv hay đổi tên ngoài Explorer/Finder.
Xóa Worktree sau khi xong	git worktree remove <đường-dẫn>	Tự động xóa cả thư mục code lẫn dữ liệu trong .git/worktrees.
Dọn rác khi lỡ xóa tay (rm -rf)	git worktree prune	Giải phóng các nhánh bị kẹt do xóa thư mục không qua lệnh Git.

Tóm tắt Bài 3 & Vấn đề đặt ra cho Bài 4

Nắm vững 6 câu lệnh trên là bạn đã có thể thao tác mượt mà với Git Worktree. Tuy nhiên, nếu nhìn kỹ lại các ví dụ ở trên, bạn sẽ thấy chúng ta đang phải dùng đường dẫn tương đối ../payment-hotfix, ../payment-review-refund nhảy ra bên ngoài thư mục gốc payment-service.

Khi bạn có 20 Microservices, và mỗi service bạn lại tạo ra 3 thư mục ../service-a-hotfix, ../service-a-feature, thư mục workspace/ ngoài cùng của bạn sẽ biến thành một bãi chiến trường hỗn loạn với 60 thư mục nằm ngang hàng nhau!

Làm thế nào để quy hoạch cây thư mục (Directory Layout) cho hàng chục Microservices một cách khoa học, gọn gàng và chuyên nghiệp nhất? Câu trả lời sẽ có trong Bài 4: Chiến lược tổ chức thư mục chuẩn chỉnh với kỹ thuật Bare Repository (git clone --bare).