Bạn đang refactor một tính năng, có cả file đã sửa và file mới chưa commit. Đúng lúc đó cần sửa lỗi đăng nhập trên nhánh phát hành. Một worktree bổ sung cho phép mở thư mục khác để làm hotfix, trong khi thư mục hiện tại vẫn giữ công việc đang dở.
Hướng dẫn dùng các lệnh Git worktree cơ bản, đối chiếu tài liệu chính thức ngày 22/10/2026. Tên nhánh, đường dẫn và remote trong ví dụ là lựa chọn cho tình huống minh họa; cần thay bằng giá trị đúng của repository đang dùng.
Worktree chia sẻ gì và tách gì?
Các worktree liên kết dùng chung repository và lịch sử Git. Mỗi thư mục có working tree, index và HEAD phục vụ lần checkout của nó. Nhờ đó, bạn có thể sửa các file trên hai nhánh trong hai thư mục mà không phải liên tục chuyển nhánh trong cùng một thư mục.
Tuy nhiên, chúng không phải hai bản sao hoàn toàn độc lập. Những thao tác thay đổi lịch sử hoặc ref dùng chung vẫn cần được hiểu rõ. Một file .env, thư mục dependency hay database cục bộ cũng không tự được sao chép sang worktree mới.
1. Ghi nhận trạng thái trước khi tạo
Chạy trong thư mục repository đang làm dở:
git --version
git status --short
git branch --show-current
git worktree list
git remote -vstatus giúp bạn nhận biết những thay đổi nào phải còn nguyên sau khi tạo hotfix. worktree list cho biết một nhánh có thể đã được mở ở thư mục khác. Không cần commit tạm chỉ để đi qua bước này, nhưng vẫn nên hiểu file mới nào chưa được Git theo dõi.
Trong phần tiếp theo, giả sử repository có remote origin và nhánh gốc cần sửa là origin/main. Nếu sản phẩm phát hành từ một nhánh release khác, dùng đúng nhánh đó. Chọn sai điểm xuất phát có thể khiến hotfix mang theo những thay đổi chưa có trong bản đang chạy.
2. Mở thư mục dành cho hotfix
git fetch origin
git worktree add -b hotfix/login-timeout ../app-hotfix origin/main
git -C ../app-hotfix status --short
git -C ../app-hotfix branch --show-current
git worktree listLệnh add -b tạo nhánh mới tại điểm xuất phát đã chỉ định, rồi checkout nó vào thư mục anh em ../app-hotfix. Sau đó, xác nhận tên nhánh trước khi sửa code. Nếu nhánh hotfix/login-timeout đã tồn tại, dừng để kiểm tra thay vì đổi sang một tùy chọn có thể reset nhánh đó.
Mở một cửa sổ editor hoặc terminal tại thư mục mới. Với dự án Node.js, việc cài dependency và cấu hình biến môi trường vẫn phải được thực hiện cho thư mục đó theo hướng dẫn repository. Không copy secret từ nơi khác theo thói quen, và không giả định hai dev server có thể dùng cùng cổng hoặc cùng database mà không ảnh hưởng nhau.
3. Sửa và kiểm tra đúng phạm vi
Thực hiện thay đổi tối thiểu cho lỗi cần sửa. Chạy bộ kiểm tra phù hợp của dự án, xem diff và xác nhận không lẫn file môi trường hoặc dữ liệu sinh ra. Ví dụ kiểm tra trạng thái:
git -C ../app-hotfix diff
git -C ../app-hotfix status --short
git status --shortLệnh cuối vẫn chạy ở worktree ban đầu, giúp đối chiếu công việc dở trước đó. Một worktree sạch ở nhánh hotfix không có nghĩa worktree gốc phải sạch; hai trạng thái này được nhìn ở hai thư mục khác nhau.
Sau khi đã rà soát, commit theo quy ước dự án và gửi hotfix qua quy trình review/release của team. Worktree không tự quyết định cách merge, cherry-pick hay triển khai. Các bước đó phụ thuộc nhánh phát hành và chính sách repository, nên không có một lệnh push phù hợp cho mọi trường hợp.
4. Dọn thư mục khi công việc đã được lưu
Trước khi dọn, bảo đảm commit và mọi dữ liệu cần giữ đã được lưu đúng nơi. Từ worktree gốc:
git -C ../app-hotfix status --short
git worktree remove ../app-hotfix
git worktree listMặc định, Git từ chối xóa worktree còn thay đổi hoặc file chưa theo dõi. Hãy xem nguyên nhân thay vì dùng --force cho qua. Một file log thử nghiệm có thể bỏ được, nhưng một file cấu hình chưa lưu hoặc dữ liệu cần giữ phải được xử lý có chủ đích.
Xóa worktree không tự xóa nhánh hotfix. Chỉ dọn nhánh theo quy trình team sau khi đã xác nhận công việc được tích hợp hoặc lưu giữ. Cũng nên dùng git worktree remove thay vì xóa thư mục bằng trình quản lý file để metadata được quản lý nhất quán.
Các vướng mắc thường gặp
Nếu Git báo nhánh đã checkout ở nơi khác, xem git worktree list và dùng thư mục đó hoặc tạo một nhánh mới đúng mục đích. Rào chắn này giúp tránh hai thư mục cùng cập nhật trạng thái của một nhánh theo cách khó kiểm soát.
Nếu cần giữ worktree trên ổ tháo rời, tìm hiểu git worktree lock và unlock trước khi tháo ổ hoặc dọn metadata. Nếu đã di chuyển thư mục ngoài Git, kiểm tra tài liệu repair; prune dùng để dọn metadata của worktree không còn tồn tại, không phải lệnh thay thế cho việc bảo toàn dữ liệu.
Kết luận
Worktree hữu ích khi bạn cần đổi ngữ cảnh mà vẫn muốn nhìn rõ mỗi công việc trong một thư mục riêng. Thói quen quan trọng là kiểm tra điểm xuất phát, nhánh đang checkout, cấu hình runtime và trạng thái cần giữ trước khi dọn.
