Git notes: Bổ sung ghi chú cho commit mà không sửa lịch sử

Một commit đã phát hành cần được bổ sung liên kết ticket hoặc kết quả kiểm tra sau triển khai. Sửa commit message lúc này có thể làm đổi danh tính commit và gây xáo trộn lịch sử chia sẻ. Git notes cung cấp một lớp ghi chú tách biệt, phù hợp để gắn thêm ngữ cảnh có thể tra cứu.

1. Ghi chú không phải nội dung commit

Theo tài liệu Git notes, notes gắn thông tin vào object mà không sửa object đó. Namespace mặc định là refs/notes/commits. Vì vậy, bổ sung note không làm thay đổi hash của commit được ghi chú.

Hãy coi đây là lớp chú giải, không phải một file mới nằm trong mã nguồn. Nó phù hợp với liên kết đến báo cáo kiểm thử, mã hồ sơ sự cố hoặc giải thích được phát hiện sau release. Những quyết định kiến trúc cần duyệt lâu dài vẫn nên có tài liệu chính thức, chủ sở hữu và quy trình cập nhật rõ ràng.

2. Thử thêm và đọc một note

Thử trong repository riêng có ít nhất một commit. Kiểm tra Git đã có danh tính tác giả cho các thao tác ghi; không thay cấu hình toàn máy chỉ để chạy ví dụ.

git rev-parse HEAD
git notes add -m "Ticket: DEMO-42; verification record: RUN-105" HEAD
git notes show HEAD
git log -1 --notes
git rev-parse HEAD

Hai lần đọc HEAD cần trả về cùng mã commit. Nếu đã có note, lệnh add với -m từ chối ghi đè; hãy đọc nội dung trước. Không thêm -f chỉ để vượt lỗi mà chưa biết thông tin nào sẽ mất.

Ví dụ dùng mã hồ sơ minh họa thay vì đường dẫn có token. Khi dùng thật, ưu tiên liên kết bền vững đến hệ thống có kiểm soát truy cập. Đừng chép credential, log chứa thông tin khách hàng hoặc toàn bộ dữ liệu sự cố vào notes.

3. Bổ sung ngữ cảnh thay vì thay thế

git notes append -m "Follow-up: reviewed in DEMO-57" HEAD
git notes show HEAD

append bổ sung nội dung; nếu chưa có note thì tạo mới. Cách này tiện cho một ghi chú theo dõi ngắn. Tuy nhiên, một chuỗi ghi chú quá dài sẽ khó đọc: nên giữ phần tóm tắt và liên kết, còn nội dung chi tiết đặt trong hồ sơ chuyên dụng.

Quy ước nhóm có thể gồm mã ticket, kết luận ngắn, ngày xác minh và người chịu trách nhiệm. Hãy phân biệt “đã chạy kiểm tra” với “đã được phép triển khai”; hai thông tin này không thay thế nhau.

4. Chia sẻ notes có chủ đích

Không giả định người khác đã nhận notes chỉ vì họ có branch chứa commit. Với quy trình dùng namespace mặc định và remote origin, sau khi xác nhận đúng đích và quyền chia sẻ:

git remote -v
git push origin refs/notes/commits

Ở checkout nhận, có thể lấy ref cụ thể:

git fetch origin refs/notes/commits:refs/notes/commits
git notes show HEAD

Người nhận phải có đúng commit cần đọc; HEAD khác sẽ đọc ghi chú của commit khác. Các lệnh truyền ref tuân theo cơ chế push và fetch. Server có thể giới hạn ref được phép ghi hoặc đọc, nên thử trên remote thử nghiệm trước.

Nếu các bản notes đã phân kỳ, dừng để kiểm tra và hợp nhất có review; không dùng force push để bỏ qua cập nhật của đồng đội. Trong quy trình nhiều người ghi, nên giao một đầu mối cập nhật hoặc thiết kế bước phối hợp rõ ràng.

5. Rebase và amend cần kiểm tra riêng

Khi lịch sử được viết lại, commit mới có danh tính khác. Git có cấu hình hỗ trợ chuyển notes qua một số thao tác viết lại, nhưng không nên mặc định quy trình nào cũng giữ đúng mọi liên kết. Sau thao tác, kiểm tra note trên commit đích và xác nhận ngữ cảnh vẫn còn đúng.

Một báo cáo kiểm thử của commit cũ không tự chứng minh commit mới vượt qua kiểm thử. Nếu thay đổi mã nguồn, hãy chạy lại bước cần thiết rồi cập nhật hồ sơ phù hợp, thay vì chỉ chuyển lời xác nhận cũ sang commit mới.

6. Checklist áp dụng trong nhóm

• Quy định loại thông tin được ghi và người có trách nhiệm cập nhật.
• Thử đọc lại notes từ checkout thứ hai sau khi truyền ref.
• Đưa notes ref vào kế hoạch sao lưu nếu quy trình phụ thuộc vào nó.
• Không dùng một câu “approved” trong note thay cho kiểm soát phê duyệt và bằng chứng xác thực.
• Kiểm tra công cụ giao diện đang dùng có hiển thị notes hay cần đọc qua dòng lệnh.

Git notes hữu ích khi nhóm cần thêm ngữ cảnh mà không sửa commit đã chia sẻ. Giá trị thực tế nằm ở quy tắc ghi, cách phân phối và khả năng kiểm chứng thông tin, không chỉ ở việc thêm được một dòng chú thích.