Git Notes: Tính năng ngầu nhất và cũng bị ghét nhất của Git (2022)

• Git notes là một công cụ mạnh mẽ cho phép đính kèm siêu dữ liệu vào commit và các đối tượng khác
• Tính năng này cho phép lưu thông tin bổ sung khi không thể sửa commit message
• Có thể dùng để lưu nhiều loại thông tin như lịch sử code review hoặc kết quả kiểm thử
• Thậm chí có thể xây dựng hệ thống code review phân tán, nhưng tính tiện dụng và độ nhận biết đều thấp
• Do thiếu hỗ trợ, chẳng hạn như bị vô hiệu hóa trên GitHub, nên mức độ được áp dụng hằng ngày rất thấp

---

Git notes là gì

• Git notes là một tính năng cho phép đính kèm siêu dữ liệu vào bất kỳ đối tượng nào được git theo dõi (commit, blob, tree)
• Thông thường, commit message sau khi đã được ghi lại thì không thể thay đổi, nhưng với git notes, có thể thêm thông tin mới mà không cần sửa nội dung commit
• Ví dụ, có thể thêm notes vào commit như bên dưới
  • git notes add -m 'Acked-by: <이메일>'
• Notes được hiển thị cùng trong git log dưới dạng một mục riêng

Các trường hợp sử dụng thực tế

• Ngay cả chính dự án git cũng dùng git notes để liên kết commit với các luồng thảo luận trong mailing list
• Các ví dụ sử dụng thực tế của notes bao gồm
  • Theo dõi thời gian làm việc theo từng commit hoặc branch
  • Lưu log code review và kết quả kiểm thử
  • Thiết kế một hệ thống code review hoàn toàn phân tán

Lưu code review và kết quả kiểm thử

• Ngày càng có nhiều trường hợp các code forge hoặc hệ thống review hỗ trợ lưu siêu dữ liệu code review theo cách ngoại tuyến, tức là ngay trong git
• Plugin reviewnotes của Gerrit hiển thị người thực hiện review và lịch sử chạy kiểm thử dưới dạng notes trong git log
  • Người dùng có thể xem lịch sử kiểm tra mã ngay trên máy cục bộ mà không cần mở trình duyệt riêng

Hệ thống code review phân tán

• Đã có những ví dụ như git-appraise do Google phát triển, hiện thực hóa code review phân tán bằng git notes
• git-appraise ghi lại toàn bộ quy trình như yêu cầu code review, bình luận về thay đổi và merge sau review vào git notes, đồng thời hoạt động độc lập, không phụ thuộc vào dịch vụ lưu trữ mã trực tuyến
• Mọi cộng tác đều có thể thực hiện trong môi trường cục bộ, và công cụ này còn cung cấp cả giao diện web

Tính tiện dụng và độ nhận biết thấp

• Git notes hầu như không được sử dụng vì giao diện bất tiện và không trực quan với người dùng phổ thông
• Kể từ năm 2014, GitHub ngừng hiển thị commit notes, khiến cơ hội sử dụng càng ít hơn
• Việc quản lý notes cho commit có thể được làm dễ hơn đôi chút bằng cấu hình git, nhưng để gắn notes vào blob hoặc tree object thì cần hiểu thêm về cấu trúc nội bộ của git (plumbing)
• Kết quả là git notes vẫn là một tính năng mang tính dành cho người đam mê và có độ nhận biết rất thấp

Tính độc lập với open forge

• Bản thân git có thể hỗ trợ quản lý phiên bản phân tán và code review, nhưng nhiều giá trị bổ sung như lịch sử review lại có xu hướng phụ thuộc mạnh vào các dịch vụ lưu trữ như GitHub
• Khai thác tính năng Git notes mở ra khả năng lưu trữ và phân phối theo cách phân tán không chỉ lịch sử thay đổi của mã nguồn mà còn cả lịch sử tổng thể của dự án
• Điều này có ý nghĩa quan trọng đối với một hệ sinh thái phát triển phân tán đúng nghĩa và việc bảo tồn hồ sơ lịch sử

[GN⁺]

Ý kiến Hacker News

• Chia sẻ rằng có một tính năng ít được biết đến là Git trailers; trailer có thể chèn metadata dạng key-value khi tạo commit. Nó được dùng trong Gerrit để gắn Change-Id. Liên kết bài viết liên quan

  • Chia sẻ rằng PostgreSQL có một tính năng tương tự là COMMENT; COMMENT có thể thêm văn bản vào các đối tượng cơ sở dữ liệu. Mong PostgreSQL cũng cung cấp khả năng chỉnh sửa metadata có cấu trúc dạng key-value. Liên kết tài liệu liên quan

  • Chia sẻ kinh nghiệm dùng git notes khi làm upstream mã nguồn mở để đánh dấu các commit đã hoàn thành unit test; điều này hữu ích khi dọn nhánh bằng git rebase -i, nhưng hiện trailer có vẻ là cách tốt hơn. Nếu các tính năng như Change-Id được tích hợp vào chính git thì có lẽ các công cụ sẽ hiểu chúng tốt hơn. Việc phân biệt commit bằng commit message có phần mong manh; commit id thì tốt về tính duy nhất, nhưng khi chuyển cùng một thay đổi sang trên một commit khác thì giá trị định danh giảm đi. Chỉnh sửa: trailer là một phần của commit nên không thể thay thế notes hoàn toàn

  • Gần đây mới biết GitHub dùng một trailer riêng thay vì [skip ci], có lẽ để dễ tách khỏi commit message hơn. Không rõ vì sao GitHub chỉ yêu cầu trailer cuối cùng, đoán là do xử lý bằng regex. Liên kết tài liệu liên quan

  • Mới biết đến tính năng trailer; với tư cách là người hâm mộ Conventional Commits, có vẻ trailer phù hợp hơn để thêm kiểu metadata này. Thắc mắc liệu việc thêm thủ công vào commit message và dùng cờ --trailer có tương đương nhau về mặt chức năng hay không

  • Muốn tích hợp tự nhiên với hệ thống issue tracking, nhưng đưa thông tin đó vào chỗ như trailer lại quá xa issue tracker nên kém hiệu quả. Issue tracker có vấn đề là chạy theo xu hướng và nhiều tính năng được bổ sung chậm; quy tắc bắt buộc phải dùng tên nhánh suy ra từ tên ticket làm tiêu đề PR thì bất tiện. Muốn liên kết commit và issue bằng metadata khác để tiêu đề PR có ý nghĩa hơn, nhưng đây không phải chuyện dễ đổi nên chỉ còn biết than thở trên Internet

• Chia sẻ rằng Forgejo đã bắt đầu hỗ trợ trailer từ phiên bản 10 phát hành vào tháng 1 năm nay. Ghi chú phát hành Pull request

• Thắc mắc về cách git notes tương tác với việc viết lại lịch sử như amend, rebase... Vì notes gắn với ID của commit/tree/blob, không rõ khi bị thay bằng commit mới thì notes có được sao chép hay biến mất hay không; và khi gộp nhiều commit bằng interactive rebase thì sẽ thế nào. Cũng chia sẻ rằng notes gắn với “nội dung” của file/thư mục là điều khác với kỳ vọng; ví dụ nếu gắn note vào blob chuỗi "Hello world!" thì không rõ note đó có áp dụng cho mọi file có cùng nội dung hay không, và khi file thay đổi thì có mất notes hay không

  • Trong git rebase và các thao tác tương tự, có thể cấu hình để notes được sao chép theo mặc định; xem tùy chọn notes.rewrite trong git-config(1)

• Hiện đang tích cực dùng git notes ở chỗ làm để lưu vết review code nội bộ mà không làm commit message rối lên hoặc phải tạo PR cho mọi thay đổi. Để lại ngữ cảnh trên nhánh như mỗi commit ánh xạ tới ticket nào, các ràng buộc hạ tầng, hoặc trong trường hợp sửa lỗi thì có thể thêm liên kết tới thread sự cố. Việc lưu thông tin này trong repo giúp dễ hiểu vì sao một dòng mã bị thay đổi mà không cần tìm trên Slack hay Jira. Nếu áp dụng ở quy mô lớn thì có thể giảm rõ rệt nhu cầu về UI của các nền tảng. Quan điểm là reproducibility không chỉ cần cho build mà còn cần cho cả “intent”

  • Thắc mắc liệu những thông tin như vậy có nên nằm luôn trong commit message không, hay mục đích là còn muốn liên kết tới cả những diễn biến về sau như “commit này đã tạo ra bug #123”

• git notes chỉ thực sự hữu ích khi cần thêm thông tin sau thời điểm commit. Các ví dụ như Acked-By hay liên kết tới thảo luận trên mailing list đều là thông tin đã biết vào lúc commit, nên chỉ cần thêm vào commit message. Ngược lại, ưu điểm thật sự của git note là có thể gắn giải thích bổ sung về sau, chẳng hạn cho các commit đã bị revert

  • Thường thì commit message tuyên bố đã sửa bug nhưng thực ra chưa sửa được; từ đó sinh ra các bug dây chuyền, và đồng nghiệp hay bỏ qua ý định ban đầu của người viết. Sau trải nghiệm khách hàng tức giận và bug tái phát thì cảm thấy cần thận trọng hơn với các “bug fix”. Đôi khi một thay đổi còn sửa nhiều bug cùng lúc, hoặc mở đường cho cải tổ, cải thiện hiệu năng hay tính năng mới

  • Acked-By, review và thảo luận vốn dĩ có thể chỉ diễn ra sau khi commit, nên tại thời điểm commit chưa thể biết. Các trường hợp revert thì ngược lại, thêm vào commit message lại hữu ích hơn, vì tính năng blame hiển thị thay đổi gần nhất nên tự nhiên cũng cung cấp khả năng lần vết tới commit đã bị revert

  • Có nhiều trường hợp thảo luận vẫn tiếp diễn cả sau khi commit

• Cho rằng đây là một điểm thú vị đáng khám phá của notes để cung cấp thêm ngữ cảnh cho các code agent

• Đây không phải vấn đề thiếu kiến thức mà là vấn đề UI; nếu GitHub hiển thị notes tốt hơn thì chúng sẽ được dùng nhiều hơn ngay

  • Mong GitHub hỗ trợ notes

• Git có rất nhiều “tính năng cực hay nhưng không được yêu thích” như bisect, pickaxe, reflog, range-diff, archive, annotated tags..., nhưng đa số mọi người chỉ xem nó như Google Drive nên không dùng đến

  • git notes dù sao cũng tạo cảm giác trùng lặp vì feature, roadmap và các ngữ cảnh phi kỹ thuật đã được theo dõi bằng công cụ quản lý dự án riêng như Jira; theo triết lý Unix thì mỗi công cụ nên tập trung vào vai trò của nó

  • Đây là lần đầu nghe tới pickaxe nên khá bất ngờ; có lẽ không nên quá tự tin

  • Những tính năng mang tính trang trí như vậy thực ra thường không hữu ích đến thế; đó là góc nhìn coi chúng như các kỹ xảo xoay quanh bản chất cốt lõi

• Ý kiến cho rằng git notes thật ra không phải một unloved feature “ngầu”, mà chỉ hữu ích trong một số tình huống rất hạn chế. Việc đưa toàn bộ thông tin cần thiết vào commit message để hệ thống khác như JIRA tham chiếu mới là điểm mạnh. Các hệ thống như JIRA còn là kênh giao tiếp với business analyst hoặc bộ phận support không phải developer; việc những người không phải developer không có quyền truy cập repo và code cũng là điều hợp lý. Trong bối cảnh làm việc với nhiều dịch vụ/repo cùng lúc, việc tham chiếu feature bằng notes là không thực tế; cần tích hợp với hệ thống bên ngoài

  • Chỉ ra rằng việc business analyst không thể truy cập code hay repo là không hiệu quả, vì có những thứ chỉ cần nhìn một dòng code là biết nhưng lại phải bị hỏi đi hỏi lại. Dù vẫn có những analyst có năng lực kỹ thuật, nhưng văn hóa này khó thay đổi là một giới hạn thực tế

• Biết đến notes lần đầu khoảng năm 2020 qua trang man; về cơ bản notes chỉ áp dụng cho repo cục bộ nên chưa có trải nghiệm sử dụng thực tế. Muốn dùng theo nhóm thì phải quyết định riêng về cấu hình pushing/fetching, nhưng đội của người viết đã không chọn cách đó