Tại sao bạn nên dùng Git Notes thay vì Amend?
Bạn vừa push code lên server thì sếp nhắc: “Thiếu Jira ID rồi em ơi!”. Lúc này, phản xạ tự nhiên của nhiều dev là dùng git commit --amend. Tuy nhiên, nếu branch đã được share cho team, hành động này sẽ làm thay đổi mã Hash của commit. Bạn sẽ rơi vào thế kẹt: buộc phải push --force và gây ra xung đột lịch sử (diverged branches) cho tất cả đồng nghiệp.
Trong một dự án thực tế với team 5 người, chúng mình từng mất gần 2 tiếng mỗi tuần chỉ để xử lý conflict do anh em amend các commit cũ để thêm link tài liệu. Git Notes chính là cứu cánh. Nó giống như việc bạn dán một tờ giấy Post-it lên hộp quà (commit) mà không cần mở hộp hay thay đổi món quà bên trong. Mã Hash vẫn giữ nguyên, nhưng thông tin bổ sung thì luôn hiển thị đầy đủ.
Điểm ăn tiền của Git Notes:
- Bảo toàn mã Hash: Thêm, sửa ghi chú thoải mái mà không lo lệch lịch sử Git.
- Commit message gọn gàng: Giữ message chính súc tích, đẩy mọi metadata (Jira ID, link PR, log build) vào Notes.
- Tự động hóa dễ dàng: Các hệ thống CI/CD có thể tự động ghi log vào commit mà không làm phiền đến quy trình code của Developer.
Thao tác cơ bản với Git Notes
Tính năng này có sẵn trong lõi Git, bạn không cần cài thêm bất kỳ plugin nào. Dưới đây là các lệnh thực chiến để bạn áp dụng ngay vào dự án.
1. Gắn ghi chú vào commit mới nhất
Để thêm nhanh một đoạn text vào commit HEAD, hãy dùng lệnh:
git notes add -m "Ticket-ID: IFZ-1234; Status: Approved by Lead"2. Đính kèm thông tin cho commit bất kỳ
Nếu muốn bổ sung thông tin cho một commit cũ (ví dụ mã hash 4f2a9b1), bạn chỉ cần trỏ đích danh nó:
git notes add -m "Đã test kỹ trên môi trường Staging - Build #452" 4f2a9b13. Cách xem ghi chú trong lịch sử
Khi gõ git log, Git sẽ tự động hiển thị phần Notes ở cuối mỗi commit nếu có. Hãy thử kiểm tra:
git log -n 1Kết quả hiển thị minh bạch như sau:
commit 4f2a9b1c...
Author: ItFromZero <[email protected]>
Date: Thu May 7 10:00:00 2026 +0700
Feature: Thêm chức năng thanh toán qua ví điện tử
Notes:
Ticket-ID: IFZ-1234; Status: Approved by LeadChia sẻ Notes với Team (Cấu hình quan trọng)
Nhiều bạn thắc mắc: “Sao mình thêm notes rồi mà đẩy lên GitHub đồng nghiệp lại không thấy?”. Thực tế, Git Notes mặc định chỉ nằm ở máy local. Để chia sẻ được, bạn cần cấu hình đồng bộ refs/notes.
Đẩy Notes lên Remote
Lệnh git push thông thường sẽ bỏ qua notes. Bạn phải chỉ định rõ:
git push origin refs/notes/*Tự động lấy Notes về (Fetch)
Để tránh việc phải gõ lệnh thủ công mỗi lần pull code, hãy thêm cấu hình sau vào file .git/config:
git config --add remote.origin.fetch "+refs/notes/*:refs/notes/*"Bây giờ, mỗi lần git fetch, toàn bộ ghi chú của team sẽ tự động đổ về máy bạn.
Ứng dụng nâng cao: Phân loại ghi chú (Namespaces)
Một mẹo cực hay là chia Notes thành các “ngăn” khác nhau. Ví dụ: một ngăn cho Dev review, một ngăn cho Bot CI/CD ghi log deployment. Việc này giúp dữ liệu không bị chồng chéo.
# Notes dành cho review code
git notes --ref review add -m "Cần tối ưu vòng lặp tại dòng 42" HEAD
# Notes dành cho hệ thống build
git notes --ref build add -m "Build-URL: http://ci.itfromzero.com/job/102" HEADĐể xem đồng thời các loại ghi chú này trong log, bạn dùng:
git log --show-notes=review --show-notes=buildTích hợp vào quy trình CI/CD thực tế
Trong các dự án chuyên nghiệp, mình thường cài đặt Script để Jenkins tự động ghi chú sau khi build thành công. Điều này giúp dev check nhanh trạng thái mà không cần rời khỏi terminal.
# Script ví dụ trong Jenkins
git notes --ref deployment add -m "Deployed to Prod at $(date)" $GIT_COMMIT
git push origin refs/notes/deploymentVề vấn đề xung đột (conflict), vì Notes bản chất là một nhánh đặc biệt, đôi khi hai người cùng sửa một ghi chú sẽ gây lỗi khi push. Cách tốt nhất là phân quyền rõ ràng: Developer chỉ ghi vào namespace review, còn Bot dùng deployment.
Git Notes là công cụ “nhỏ nhưng có võ”. Nó giúp giữ lịch sử commit sạch đẹp nhưng vẫn tải được lượng metadata khổng lồ, giúp quy trình làm việc của team chuyên nghiệp hơn hẳn.
