Git: Hướng dẫn viết commit message

Lộc Lee
ZaloPay Engineering
7 min readJun 29, 2019
Source: xkcd.com

Ở bài hướng dẫn này, bạn sẽ hiểu commit là gì, tầm quan trọng của việc viết message tốt cho commit của bạn, những cách thực hành tốt nhất, một số mẹo để lên kế hoạch viết commit và viết/viết lại một lịch sử commit cho tốt.

Bài viết này là một bản dịch tiếng Việt (do chúng tôi contribute) từ tài liệu Commit-message-guide của tác giả Romulo Oliveira

“Commit” là gì?

Hãy nghĩ đơn giản, một commit là một ảnh (hoặc bản sao) của những file cục bộ trên kho lưu trữ cá nhân của bạn. Khác với suy nghĩ của nhiều người, git không chỉ lưu những khác biệt giữa các phiên bản của file mà lưu trữ toàn bộ các phiên bản. Đối với những file không có sự thay đổi so với phiên commit trước, thay vì lưu một file mới, việc git làm đơn giản sẽ là lưu trữ một link trỏ tới file đã được lưu trước đó.

Hình sau mô tả cách mà git lưu trữ dữ liệu theo thời gian, trong đó mỗi một “phiên bản” là một commit:

Tại sao những commit message lại quan trọng?

  • Làm cho việc đánh giá code trở nên nhanh chóng và hiệu quả hơn.
  • Để giúp người khác hiểu về những sự thay đổi.
  • Để giải thích lý do “tại sao” chỉ giải thích bằng code là chưa đủ mà còn phải thêm bằng message.
  • Để sau này, những người bảo trì project có thể tìm ra lý do tại sao lại có những thay đổi và chúng được thực hiện như thế nào, điều này làm cho việc khắc phục sự cố cũng như gở lỗi trở nên dễ dàng hơn.

Để hiểu thêm về những điểm trên, chúng ta có thể sử dụng các good practices và những tiêu chuẩn được mô tả bên dưới.

Good Practices

Đây là những cách làm tốt mà tác giả Romulo Oliveira thu thập từ kinh nghiệp thực tế, bài báo trên internet cũng như như một số bài hướng dẫn khác.

Dùng thể mệnh lệnh(imperative form)

Nhưng tại sao phải dùng thể mệnh lệnh?
Một commit message mô tả các thay đổi được gởi lên này thực sự làm những gì, tác động của nó, chứ không phải nói về những việc đã được thực hiện.

Bài báo tuyệt vời của Chris Beams cung cấp cho chúng ta một mẫu câu đơn giản mà ta có thể dùng, giúp chúng ta viết commit message tốt hơn ở thể mệnh lệnh như sau:

If applied, this commit will <commit message>

Mỗi khi viết commit message ta ráp commit message của ta vào đoạn trên nếu trôi chảy thì câu commit message của ta đã ổn. Xem ví dụ sau:

Ví dụ:

Viết hoa chữ cái đầu

Lý do là chúng ta phải tuân theo luật ngữ pháp về việc viết hoa chữ cái đầu tiên của câu.

Việc sử dụng practice này có thể khác nhau tùy từng người, từng team, hoặc giữa các ngôn ngữ. Viết hoa hay không thì điều quan trọng là phải tuân theo một tiêu chuẩn duy nhất, không được đan xen tùy lúc.

Cố gắng truyền đạt những gì thay đổi gây ra mà không cần phải xem mã nguồn.

Việc này rất hữu ích trong nhiều tình huống (Ví dụ: Nhiều commit, có một vài thay đổi và cấu trúc lại) để giúp những người đánh giá có thể hiểu người commit đã nghĩ gì.

Sử dụng phần thân của message để giải thích “tại sao”, “để làm gì”, “như thế nào” cùng với một số chi tiết bổ sung

Phần tiêu đề và phần thân của message phải được ngăn ra bởi một dòng trống. Những dòng trống phía dưới dòng trống đó(nếu có) sẽ được xem như thuộc phần thân của message.

Những kí tự như -, * và ` là những yếu tố message dễ đọc hơn.

Tránh những message có nội dung chung chung hoặc những message mà không hề có bối cảnh

Giới hạn số lượng chữ cái.

Bạn nên sử dụng tối đa 50 ký tự cho phần chủ đề và 72 ký tự mỗi dòng cho phần thân message.

Có sự nhất quán trong việc sử dụng ngôn ngữ

Đối với chủ dự dán: Chọn một ngôn ngữ và viết mọi commit message bằng ngôn ngữ đó. Lý tưởng nhất là ngôn ngữ dùng cho commit message phải khớp với các code comment, ngôn ngữ dịch mặc định (đối với những dự án được bản địa hóa), v.v...

Đối với những người tham gia đóng góp: Viết commit message bằng ngôn ngữ tương tự ngôn ngữ của các commit message trước đó.

Commit message mẫu

Đây là mẫu commit message, được viết ban đầu bởi Tim Pope và xuất hiện trong cuốn Pro Git Book.

Phiên bản Tiếng Việt:

Rebase vs. Merge

Chương này là một TL;DR(bản tóm tắt ngắn gọn) của bài hướng dẫn tuyệt vời từ Atlassian, “Merging vs. Rebasing”.

Rebase

TL;DR: Gắn các commit trên nhánh của bạn, từng cái một, lên branch gốc, tạo ra một cây mới.

Merge

TL;DR: tạo một commit mới, gọi là(một cách thích hợp) một merge commit, chứa tất cả những sự khác nhau giữa 2 branch.

Tại sao một số người thích rebase hơn merge?

Tác giả Romulo Oliveira đặc biệt thích rebase hơn merge. Có những lý do sau:

  • Nó sinh ra một lịch sử “sạch”, không có những merge commit không cần thiết.
  • Bạn thấy gì bạn sẽ nhận cái đó, i.e., trong lúc đánh giá code, ta sẽ thấy được mọi thay đổi từ các commit cụ thể và có tên, tránh những thay đổi ẩn nằm trong các merge commits.
  • Nhiều merges được giải quyết bởi người commit hơn, và mỗi một sự thay đổi do merge gây ra sẽ nằm commit với message phù hợp.
  • Thông thường ta sẽ không khai thác cũng như đánh giá những merge commit, vì thế tránh chúng để đảm bảo mọi thay đổi điều có commit chứa thay đổi đó.

Khi nào cần squash

“Squashing” là quá trình lấy một dãy commit và ép lại thành một commit duy nhất.

Sẽ rất hữu ích trong một vài tình huống, ví dụ:

  • Giảm những commit ít hoặc không có ngữ cảnh (sửa lỗi chính tả, định dạng, nội dung bị quên)
  • Kết hợp những sự thay đổi riêng biệt, những thay đổi này có ý nghĩa hơn khi áp dụng cùng nhau.
  • Viết lại những commit kiểu công việc đang tiếng hành.

Khi nào nên tránh rebase hoặc squash?

Tránh rebase và squash ở những commit công khai hoặc những nhánh đồng sở hữu nơi nhiều người cùng làm việc trên nhánh đó. Rebase và squash viết lại history và ghi đè lên các commit hiện có, thực hiện nó trên những commit trên những nhánh đồng sở hữu (ví dụ, commit được đẩy đến một kho lưu trữ từ xa hoặc đến từ những nhánh khác) có thể gây bối rối và mọi người có thể mất những thay đổi của họ (cục bộ lẫn từ xa) bởi những cây phân nhánh và xung đột(divergent trees and conflicts).

Những git command hữu ích

rebase -i

Sử dụng để squash những commit, sửa messages, viết lại/xóa/sắp xếp lại những commit, v,v…

fixup

Sử dụng để dọn dẹp các commit một cách dễ dàng và không cần rebase phức tạp. Bài báo này có những ví dụ tốt về cách thức cũng như khi nào thì nên sử dụng fixup.

cherry-pick

cherry-pick Khi bạn commit sai nhánh, sử dụng cherry-pick để lấy một commit trên nhánh sai và áp dụng vào nhánh mình muốn, thay vì phải code lại từ đầu.

Ví dụ:

add/checkout/reset [ — patch | -p]

Tưởng tượng chúng ta có những sự khác biệt sau:

Chúng ta có thể dùng git add -p để thêm duy nhất chỗ mà ta muốn, không cần phải thay đổi code đã được viết. Sẽ hữu ích khi chia một thay đổi lớn thành những commit nhỏ hơn hoặc reset/checkout một thay đổi cụ thể.

Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.

hunk 1

hunk 2

hunk 3

Những thứ thú vị khác có thể tham khảo:

Thích tài liệu này?

Gởi lời cảm ơn tới RomuloOliveira!

Nguồn và đọc thêm

Cùng tham gia đóng góp bản dịch

  • Lê Phước Lộc
  • Nguyễn Quốc Vương
  • Hoàng Thiên Nữ

--

--