Đã đăng vào thg 9 4, 2016 6:33 CH 7 phút đọc

1.7K

Làm thế nào để viết một git commit message tốt?

Bài đăng này đã không được cập nhật trong 2 năm

Làm thế nào để viết một git commit message tốt?

Là một Developer thì git commit message không còn xa lạ gì với các bạn nữa. Tuy nhiên, để viết một git commit message tốt thì không phải ai cũng làm được. Vậy tại sao git commit message tốt lại quan trọng, và làm thế nào để viết một commit message tốt?

Tại sao một commit message tốt lại quan trọng

Nếu bạn duyệt qua các bản ghi của bất kỳ git repository nào, bạn có thể tìm thấy một đống các commit message hỗn độn. Ví dụ như sau:

$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"

e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing

Nếu so sánh với commit messages sau:

$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"

5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage

Như bạn có thể thấy đó là những commit messages khác nhau rất nhiều trong cả format và chiều dài message. Đó là tính không nhất quán.

Các contributors biết rằng một git commit message tốt là hoàn cảnh giao tiếp tốt nhất giữa các developers và chính họ trong tương lai. Một Diff sẽ nói cho bạn biết cái gì thay đổi, nhưng một commit message mới có thể cho bạn biết tại sao cần những thay đổi đó.

Một commit message tốt sẽ hữu ích trong các trường hợp git blame, git revert, git rebase, git log, git shortlog.

Một project "dài hơi" thành công dựa trên một phần lớn khả năng bảo trì của nó. Nên ngay từ lúc bắt đầu project ta nên dành thời gian cho việc học tập và quan tâm đến commit message, ban đầu có thể rất rắc rối nhưng khi thành lập thói quen rồi thì việc đó trở lên đơn giản và hiệu quả.

Để tạo ra một commit message hữu ích, đội phát triển nên tuân thủ commit message convention mà định nghĩa bởi ít nhất 3 điều sau:

Style cú pháp Markup, căn lề, ngữ pháp, viết hoa, dấu chấm câu.
Content nội dung mà commit message nên chứa? Những nội dung không nên có trong commit message?
Metadata Làm thế nào để theo dõi các issue IDs, số pull requests...

May mắn thay, có những quy ước được thiết lập giúp bạn viết commit message tốt hơn. Tuân theo bảy nguyên tắc dưới đây và bạn đang trên con đường trở thành pro commit message.

7 quy tắc cho một git commit message tốt

Subject riêng biệt với 1 dòng trống
Giới hạn subject với 50 ký tự
Viết in hoa đầu subject
Không kết thúc dòng subject với dấu chấm câu
Sử dụng Imperative mood trong dòng subject
Phần body giới hạn 72 ký tự
Sử dụng body để mô tả how và why của commit

Sau đây tôi sẽ đề cập đến từng quy tắc cụ thể

Chủ đề riêng biệt với 1 dòng trống

Thứ nhất, không phải mọi commit message đều cần subject và body. Đôi khi chỉ cần dùng subject là đủ cho những trường hợp thay đổi đơn giản, không có bối cảnh. Ví dụ:

Fix typo in introduction to user guide

Tuy nhiên, một commit chứa một ít giải thích và ngữ cảnh thì bạn cần phải viết body cho nó. Ví dụ

Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

Khi ta check full log commit sẽ hiển thị như sau:

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

 Derezz the master control program

 MCP turned out to be evil and had become intent on world domination.
 This commit throws Tron's disc into MCP (causing its deresolution)
 and turns it back into a chess game.

Nếu muốn check log với git log --oneline sẽ in ra chỉ dòng subject:

$ git log --oneline
42e769 Derezz the master control program

Như vậy thì viết commit message với một dòng trống sau nó sẽ giúp bạn check log một cách dễ dàng với kiểu short log và full log.

Giới hạn subject với 50 ký tự

Giới hạn 50 ký tự không phải là một giới hạn không đổi. Giữ chiều dài của subject và phải đảm bảo rằng nó có thể đọc được (câu có nghĩa), như vậy buộc người viết phải suy nghĩ để viết một subject ngắn gọn và đủ nội dung.

GitHub UI chứa đầy đủ các quy tắc conventions, nó sẽ nhắc nhở bạn nếu commit subject của bạn vượt quá 50 ký tự.

và sẽ cắt dòng nếu subject của bạn dài hơn 69 ký tự và thêm vào dấu 3 chấm

Viết in hoa đầu subject

Đơn giản là bạn viết in hoa ở đầu subject. =))

Không kết thúc dòng subject với dấu chấm câu

Dấu chấm câu không thật sự cần thiết trong subject. Bạn nên tiết kiệm không gian đề giữ cho subject của bạn trong giới hạn 50 ký tự. Ví dụ

Open the pod bay doors

thay vì

Open the pod bay doors.

Sử dụng Imperative mood trong dòng subject

Imperative mood có nghĩa là nói hay viết như thể đưa ra một lệnh hoặc chỉ dẫn. Một vài ví dụ:

Clean your room
Close the door
Take out the trash

Các mệnh lệnh có thể có đôi chút thô lỗ, đó là nguyên nhân mà chúng ta không thường xuyên sử dụng nó. Tuy nhiên, nó hoàn hảo cho việc dùng làm subject. Một lý do cho điều này đó là chính Git đã sử dụng mệnh lệnh để làm subject commit message cho bạn. Ví dụ:

Merge branch 'myfeature'

hay

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

Một git commit subject đúng format luôn luôn hoàn thành các câu sau:

If applied, this commit will *your subject line here*

Ví dụ:

If applied, this commit will refactor subsystem X for readability

Phần body giới hạn 72 ký tự

Git không tự động wrap text. Bạn cần làm nó bằng tay. Khuyến cáo cho rằng 72 ký tự là giới hạn hợp lý cho phần body.

Sử dụng body để mô tả how và why của commit

Đây là ví dụ tốt để mô tả cái gì thay đổi và tại sao của commit from Bitcoin Core

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.

Bạn có thể thấy phần body chứa nội dung tại sao cần những thay đổi trong commit này, và những thay đổi đó là gì. Trong tương lai khi dự án vào quá trình maintain thì có khi chính bạn phải cảm ơn mình khi đã viết commit message này.

Lời kết

Những quy tắc đơn giản để viết một commit message tốt được đề cập ở trên. Tuy chỉ gồm 7 quy tắc đơn giản nhưng để tạo ra một commit message tốt thì bạn cần hình thành thói quen và tư duy. Và luôn nhớ rằng một commit message tốt có thể giúp bạn tiết kiệm nhiều thời gian và công sức trong tương lai.