Cách viết một thông báo cam kết Git hiệu quả, hữu ích

Thông báo cam kết là các mô tả ngắn về từng cam kết trong hệ thống kiểm soát phiên bản như Git. Khi bạn thực hiện các thay đổi đối với các tệp dự án của mình, bạn nên cung cấp một thông báo giải thích những gì chúng thực hiện hoặc tại sao bạn thực hiện chúng.

Thông báo cam kết phục vụ như một dạng tài liệu và thông tin liên lạc. Chúng đóng một vai trò quan trọng trong việc duy trì lịch sử phiên bản rõ ràng và có tổ chức của một dự án. Tìm hiểu cách viết thông điệp cam kết tốt và các thành viên khác trong nhóm của bạn sẽ đánh giá cao công việc của bạn hơn nữa.

Cấu trúc của một thông điệp cam kết tốt

Một ví dụ điển hình về thông báo cam kết bao gồm bốn phần: Loại, Mô tả, Nội dung và Chân trang.

Như vậy:

 <type>: <description>
[optional body]
[optional footer]
 

Kiểu

Loại mô tả loại thay đổi được thực hiện trong cam kết hiện tại. Bạn có thể sử dụng bất kỳ hệ thống nào phù hợp với hoàn cảnh của mình. Ví dụ: đây là một số từ khóa mẫu mà bạn có thể sử dụng để báo hiệu từng loại thay đổi, bên cạnh việc sử dụng ví dụ:

• chiến công: thay đổi của bạn giới thiệu một tính năng mới.
• sửa chữa: bạn sửa một lỗi.
• cấu trúc lại: thay đổi mã cấu trúc lại của bạn mà không sửa lỗi hoặc thêm tính năng mới.
• Bài kiểm tra: bạn thực hiện bất kỳ thay đổi nào liên quan đến thử nghiệm. Ví dụ: khi bạn viết bài kiểm tra với Jest hoặc bất kỳ khung kiểm tra nào khác mà bạn chọn.
• việc vặt: các thay đổi không liên quan đến bản sửa lỗi, tính năng hoặc thử nghiệm. Ví dụ: cập nhật phụ thuộc.
• tài liệu: khi bạn cập nhật tài liệu.
• phong cách: các thay đổi không ảnh hưởng đến ý nghĩa của mã, chẳng hạn như thêm khoảng trắng, thiếu dấu chấm phẩy, v.v.
• hoàn hảo: thay đổi liên quan đến cải tiến hiệu suất.
• xây dựng: khi bạn thực hiện các thay đổi ảnh hưởng đến các tệp bản dựng.
• ci: các thay đổi liên quan đến tích phân liên tục.
• hoàn nguyên: khi quay trở lại một lần xác nhận trước đó.

Sự miêu tả

“Mô tả” của một thông báo cam kết là một bản tóm tắt ngắn gọn và mang tính mô tả về những thay đổi được thực hiện trong cam kết. Nó phục vụ như một tiêu đề nắm bắt được bản chất của cam kết.

Khi viết mô tả, hãy ghi nhớ những điều sau:

• Làm cho nó đủ rõ ràng và cụ thể để mô tả cam kết trong nháy mắt.
• Làm cho nó ngắn gọn và súc tích. Lý tưởng nhất là giới hạn nó trong 50 ký tự hoặc ít hơn sẽ là tốt nhất.
• Hãy viết nó ở thì hiện tại, ngay cả khi bạn đang mô tả những thay đổi đã được thực hiện.
• Tận dụng tâm trạng bắt buộc trong khi viết nó.
• Bắt đầu nó bằng một chữ in hoa.
• Đừng kết thúc nó bằng một khoảng thời gian.

Ví dụ:

 feat: Implement dark mode toggle for home page
 

Ví dụ này cho thấy cách bạn có thể viết mô tả cho một cam kết triển khai chế độ tối. Nó sử dụng chiến công gõ vì nó giới thiệu một tính năng mới.

Thân máy (Tùy chọn)

Phần nội dung của thông báo cam kết cung cấp thêm chi tiết và ngữ cảnh về những thay đổi được thực hiện trong cam kết. Không phải lúc nào bạn cũng cần một nội dung, nhưng nó có thể giúp cung cấp thêm thông tin, giải thích lý do thay đổi hoặc mô tả bất kỳ cân nhắc kỹ thuật nào.

Dưới đây là một số điều cần lưu ý khi viết phần nội dung của thông báo cam kết:

• Git không bao giờ tự động ngắt dòng văn bản, vì vậy hãy ngắt dòng theo cách thủ công ở 72 ký tự khi bạn viết phần nội dung. Điều này giúp Git có đủ chỗ để thụt lề văn bản, giúp văn bản dễ đọc hơn.
• Sử dụng phần thân để giải thích những gì đã xảy ra trong thay đổi, tại sao bạn thực hiện thay đổi và lý do đằng sau thay đổi của bạn.
• Bạn cần chừa một dòng trống giữa dòng mô tả và nội dung. Điều này cho phép Git phân biệt giữa chúng.
• Nếu cam kết đưa ra nhiều thay đổi hoặc ảnh hưởng đến các khu vực khác nhau của cơ sở mã, hãy cân nhắc sử dụng dấu đầu dòng hoặc đoạn văn để chia nhỏ các sửa đổi. Điều này cải thiện khả năng đọc và giúp người đọc hiểu các khía cạnh khác nhau của cam kết.

Ví dụ:

 feat: Add GitHub as an OAuth provider
Integrate GitHub as an OAuth provider to enable seamless 
authentication with GitHub accounts.
- Implement OAuth authentication flow with GitHub API
- Configure necessary endpoints and settings for GitHub authentication
- Update user interface to include GitHub login option 

Ví dụ trên cho thấy một thông báo cam kết Git tốt cho một tính năng bổ sung GitHub làm nhà cung cấp OAuth cho ứng dụng của bạn. Thông báo cam kết này có một dòng tóm tắt ngắn gọn (50 ký tự trở xuống), một văn bản giải thích chi tiết hơn (được gói gọn trong khoảng 72 ký tự) và các dấu đầu dòng để biết thêm thông tin.

Phần chân trang trong thông báo cam kết là một phần tùy chọn cung cấp thông tin bổ sung hoặc siêu dữ liệu liên quan đến cam kết. Nó thường được đặt sau phần nội dung, được phân tách bằng một dòng trống. Chân trang có thể bao gồm nhiều loại thông tin khác nhau, chẳng hạn như tham chiếu đến các vấn đề liên quan, thẻ hoặc ghi chú đặc biệt.

Khi tham chiếu các vấn đề, yêu cầu kéo hoặc các mục liên quan khác, hãy sử dụng cú pháp hoặc định dạng phù hợp theo yêu cầu của hệ thống theo dõi vấn đề của dự án của bạn. Điều này đảm bảo rằng các tài liệu tham khảo được nhận dạng và liên kết đúng cách.

Ví dụ:

 feat: Add GitHub as OAuth provider
Integrate GitHub as an OAuth provider to enable seamless 
authentication with GitHub accounts.
- Implement OAuth authentication flow with GitHub API
- Configure necessary endpoints and settings for GitHub authentication
- Update user interface to include GitHub login option
Resolves: #123
See also: #456, #789
 

Chân trang tham chiếu vấn đề liên quan #123 và đề cập đến các vấn đề liên quan khác #456 và #789 để biết thêm ngữ cảnh.

Thêm thông báo cam kết

Bạn có thể viết thông báo cam kết bằng cách sử dụng -m cờ theo sau là thông báo cam kết được đặt trong dấu ngoặc kép (tùy chọn nhưng được khuyến nghị).

Các -m cờ lý tưởng cho các thông báo cam kết ngắn, thường bao gồm loại và mô tả.

Ví dụ:

 git commit -m "chore: Change linter to ESlint"
 

Tuy nhiên, khi thông báo cam kết của bạn yêu cầu chi tiết hơn, chẳng hạn như phần nội dung và chân trang, tốt hơn hết bạn nên viết cam kết trong trình soạn thảo văn bản hoặc IDE.

Ngoài ra, bạn có thể viết các thông điệp cam kết dài trong một tệp văn bản và sử dụng –tài liệu cờ để chỉ định các thông báo cam kết là nội dung của tệp văn bản.

Ví dụ:

 git commit --file commit_message.txt
 

Khi bạn chạy lệnh trên, git sẽ sử dụng nội dung của tệp làm thông báo cam kết.

Bạn cũng có thể yêu cầu git mở trình chỉnh sửa mặc định của mình để viết một tin nhắn dài hơn. Nếu bạn đã đặt biến môi trường GIT_EDITOR hoặc EDITOR, git sẽ mở chương trình đó khi bạn chạy chương trình trần cam kết git yêu cầu.

Tại sao bạn nên viết thông điệp cam kết tốt

Viết thông báo cam kết tốt là rất quan trọng để cộng tác hiệu quả và bảo trì mã. Các thông báo rõ ràng và mang tính mô tả giúp hiểu, gỡ lỗi và đánh giá mã. Họ thậm chí có thể đóng góp vào tài liệu dự án hoặc ghi chú phát hành.

Chúng cho phép chia sẻ kiến ​​thức, giới thiệu trơn tru và hỗ trợ kiểm soát phiên bản. Việc ưu tiên các thông báo cam kết chất lượng giúp tăng cường quy trình phát triển và đảm bảo khả năng duy trì cơ sở mã.