一篇如何编写 Git commit Message 的文章，根据几篇博客整理而来，参考在文末
The importance of a concise and consistent commit message
Which would you rather read?
$ 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
or
$ 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
That’s why we should write commit message concise and consistent.
Re-establishing the context of a piece of code is wasteful.
重新理解不同版本代码之间的关系很浪费时间
Spent little time using git log and related tools
Had no idea what makes a great Git commit message
That’s a vicious cycle.
A well-cared for log is a beautiful and useful thing.
-
git blame -
git revert -
git rebase -
git log -
git shortlog
Reviewing others’ commits and pull requests becomes something worth doing, and suddenly can be done independently.
Understanding why something happened months or years ago becomes not only possible but efficient.
What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved
How to write an individual commit message
In order to create a useful revision history, teams should first agree on a commit message convention
-
Style
-
Content
-
Metadata
Follow the seven rules below and you’re on your way to committing like a pro.
The seven rules of a great Git commit message
-
Separate subject from body with a blank line
用空行分割主题和正文
-
Limit the subject line to 50 characters
主题不超过50个字符
-
Capitalize the subject line
主题行首字母大写
-
Do not end the subject line with a period
主题行结尾不要加句号
-
Use the imperative mood in the subject line
主题使用祈使语气
-
Wrap the body at 72 characters
正文包装为72个字符
-
Use the body to explain What and Why vs. How
正文部分解释是什么（言简意赅），为什么（重点介绍），怎么实现的（你的代码会解释这部分）
Write an example of commit message This message was written to show the format of the qualified submission information.(What?) It can make developers write commit message concise and consistent. Facilitate the development process. Make develop easy and efficient.(Why? Key Point) Are there side effects or other unintuitive consequences of this change? Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here If you use an issue tracker, put references to them at the bottom, like this: Resolves: #123 See also: #456, #789
Separate subject from body with a blank line
Of course, not every commit requires both a subject and a body.
Sometimes a single line is fine, especially when the change is so simple that no further context is necessary.
Fix typo in introduction to user guide
if the reader wonders what the typo was, she can simply take a look at the change itself
-
git show -
git diff -
git log -p
Write a body when a commit merits a bit of explanation and context.
The separation of subject from body pays off when browsing the log.
Why？Just try git log --oneline or git shortlog
Limit the subject line to 50 characters
Shoot for 50 characters, but consider 72 the hard limit.
Capitalize the subject line
Remember:
- Fix a bug which makes the program exit unexpectedly
Instead of:
- fix a bug which makes the program exit unexpectedly
Do not end the subject line with a period
Concise rather than trailing punctuation
Remember:
- Fix a bug which makes the program exit unexpectedly
Instead of:
- Fix a bug which makes the program exit unexpectedly.
Use the imperative mood in the subject line
Spoken or written as if giving a command or instruction
Git itself uses the imperative whenever it creates a commit on your behalf.
Example:
-
Refactor subsystem X for readability
-
Update getting started documentation
-
Remove deprecated methods
-
Release version 1.0.0
A properly formed Git commit subject line should always be able to complete the following sentence:
If applied, this commit will (your subject line here)
Example:
-
If applied, this commit will refactor subsystem X for readability
-
If applied, this commit will update getting started documentation
-
If applied, this commit will remove deprecated methods
-
If applied, this commit will release version 1.0.0
-
If applied, this commit will merge pull request #123 from user/branch
But, it doesn’t work for the other non-imperative forms
-
If applied, this commit will
fixed bug with Y
-
If applied, this commit will
changing behavior of X
-
If applied, this commit will
more fixes for broken stuff
-
If applied, this commit will
sweet new API methods
Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.
Wrap the body at 72 characters
Take care of it
Use the body to explain What and Why vs. How
The commit below is a great example of explaining what changed and why:
（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.
Just focus on making clear the reasons why you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did.
Reference
Blog：
who-t.blogspot.com/2009/12/on-…
Note：
