A place to cache linked articles (think custom and personal wayback machine)
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

index.md 22KB

il y a 4 ans
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384
  1. title: How to Write a Git Commit Message
  2. url: https://chris.beams.io/posts/git-commit/
  3. hash_url: 47c163111260f462fa10532e784a4c44
  4. <p><a href="#intro">Introduction</a>
  5. | <a href="#seven-rules">The Seven Rules</a> | <a href="#tips">Tips</a></p>
  6. <hr/>
  7. <h2 id="intro">Introduction: Why good commit messages matter</h2>
  8. <p>If you browse the log of any random Git repository, you will probably find its commit messages are more or less a mess. For example, take a look at <a href="https://github.com/spring-projects/spring-framework/commits/e5f4b49?author=cbeams">these gems</a> from my early days committing to Spring:</p>
  9. <div class="highlighter-rouge"><pre class="highlight"><code>$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"
  10. 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.
  11. 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)
  12. 147709f Tweaks to package-info.java files
  13. 22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
  14. 7f96f57 polishing
  15. </code></pre>
  16. </div>
  17. <p>Yikes. Compare that with these <a href="https://github.com/spring-projects/spring-framework/commits/5ba3db?author=philwebb">more recent</a> commits from the same repository:</p>
  18. <div class="highlighter-rouge"><pre class="highlight"><code>$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"
  19. 5ba3db6 Fix failing CompositePropertySourceTests
  20. 84564a0 Rework @PropertySource early parsing logic
  21. e142fd1 Add tests for ImportSelector meta-data
  22. 887815f Update docbook dependency and generate epub
  23. ac8326d Polish mockito usage
  24. </code></pre>
  25. </div>
  26. <p>Which would you rather read?</p>
  27. <p>The former varies in length and form; the latter is concise and consistent.<br/>
  28. The former is what happens by default; the latter never happens by accident.</p>
  29. <p>While many repositories’ logs look like the former, there are exceptions. The <a href="https://github.com/torvalds/linux/commits/master">Linux kernel</a> and <a href="https://github.com/git/git/commits/master">Git itself</a> are great examples. Look at <a href="https://github.com/spring-projects/spring-boot/commits/master">Spring Boot</a>, or any repository managed by <a href="https://github.com/tpope/vim-pathogen/commits/master">Tim Pope</a>.</p>
  30. <p>The contributors to these repositories know that a well-crafted Git commit message is the best way to communicate <em>context</em> about a change to fellow developers (and indeed to their future selves). A diff will tell you <em>what</em> changed, but only the commit message can properly tell you <em>why</em>. Peter Hutterer <a href="http://who-t.blogspot.co.at/2009/12/on-commit-messages.html">makes this point</a> well:</p>
  31. <blockquote>
  32. <p>Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to <a href="http://www.osnews.com/story/19266/WTFs_m">reducing it</a> [as much] as possible. Commit messages can do exactly that and as a result, <em>a commit message shows whether a developer is a good collaborator</em>.</p>
  33. </blockquote>
  34. <p>If you haven’t given much thought to what makes a great Git commit message, it may be the case that you haven’t spent much time using <code class="highlighter-rouge">git log</code> and related tools. There is a vicious cycle here: because the commit history is unstructured and inconsistent, one doesn’t spend much time using or taking care of it. And because it doesn’t get used or taken care of, it remains unstructured and inconsistent.</p>
  35. <p>But a well-cared for log is a beautiful and useful thing. <code class="highlighter-rouge">git blame</code>, <code class="highlighter-rouge">revert</code>, <code class="highlighter-rouge">rebase</code>, <code class="highlighter-rouge">log</code>, <code class="highlighter-rouge">shortlog</code> and other subcommands come to life. 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.</p>
  36. <p>A project’s long-term success rests (among other things) on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth taking the time to learn how to care for one properly. What may be a hassle at first soon becomes habit, and eventually a source of pride and productivity for all involved.</p>
  37. <p>In this post, I am addressing just the most basic element of keeping a healthy commit history: how to write an individual commit message. There are other important practices like commit squashing that I am not addressing here. Perhaps I’ll do that in a subsequent post.</p>
  38. <p>Most programming languages have well-established conventions as to what constitutes idiomatic style, i.e. naming, formatting and so on. There are variations on these conventions, of course, but most developers agree that picking one and sticking to it is far better than the chaos that ensues when everybody does their own thing.</p>
  39. <p>A team’s approach to its commit log should be no different. In order to create a useful revision history, teams should first agree on a commit message convention that defines at least the following three things:</p>
  40. <p><strong>Style.</strong> Markup syntax, wrap margins, grammar, capitalization, punctuation. Spell these things out, remove the guesswork, and make it all as simple as possible. The end result will be a remarkably consistent log that’s not only a pleasure to read but that actually <em>does get read</em> on a regular basis.</p>
  41. <p><strong>Content.</strong> What kind of information should the body of the commit message (if any) contain? What should it <em>not</em> contain?</p>
  42. <p><strong>Metadata.</strong> How should issue tracking IDs, pull request numbers, etc. be referenced?</p>
  43. <p>Fortunately, there are well-established conventions as to what makes an idiomatic Git commit message. Indeed, many of them are assumed in the way certain Git commands function. There’s nothing you need to re-invent. Just follow the <a href="#seven-rules">seven rules</a> below and you’re on your way to committing like a pro.</p>
  44. <h2 id="seven-rules">The seven rules of a great Git commit message</h2>
  45. <blockquote>
  46. <p><em>Keep in mind: <a href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html">This</a> <a href="https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines">has</a> <a href="https://github.com/torvalds/subsurface-for-dirk/blob/master/README#L92-L120">all</a> <a href="http://who-t.blogspot.co.at/2009/12/on-commit-messages.html">been</a> <a href="https://github.com/erlang/otp/wiki/writing-good-commit-messages">said</a> <a href="https://github.com/spring-projects/spring-framework/blob/30bce7/CONTRIBUTING.md#format-commit-messages">before</a>.</em></p>
  47. </blockquote>
  48. <ol>
  49. <li><a href="#separate">Separate subject from body with a blank line</a></li>
  50. <li><a href="#limit-50">Limit the subject line to 50 characters</a></li>
  51. <li><a href="#capitalize">Capitalize the subject line</a></li>
  52. <li><a href="#end">Do not end the subject line with a period</a></li>
  53. <li><a href="#imperative">Use the imperative mood in the subject line</a></li>
  54. <li><a href="#wrap-72">Wrap the body at 72 characters</a></li>
  55. <li><a href="#why-not-how">Use the body to explain <em>what</em> and <em>why</em> vs. <em>how</em></a></li>
  56. </ol>
  57. <p>For example:</p>
  58. <div class="highlighter-rouge"><pre class="highlight"><code>Summarize changes in around 50 characters or less
  59. More detailed explanatory text, if necessary. Wrap it to about 72
  60. characters or so. In some contexts, the first line is treated as the
  61. subject of the commit and the rest of the text as the body. The
  62. blank line separating the summary from the body is critical (unless
  63. you omit the body entirely); various tools like `log`, `shortlog`
  64. and `rebase` can get confused if you run the two together.
  65. Explain the problem that this commit is solving. Focus on why you
  66. are making this change as opposed to how (the code explains that).
  67. Are there side effects or other unintuitive consequences of this
  68. change? Here's the place to explain them.
  69. Further paragraphs come after blank lines.
  70. * Bullet points are okay, too
  71. * Typically a hyphen or asterisk is used for the bullet, preceded
  72. by a single space, with blank lines in between, but conventions
  73. vary here
  74. If you use an issue tracker, put references to them at the bottom,
  75. like this:
  76. Resolves: #123
  77. See also: #456, #789
  78. </code></pre>
  79. </div>
  80. <h3 id="separate">1. Separate subject from body with a blank line</h3>
  81. <p>From the <code class="highlighter-rouge">git commit</code> <a href="https://www.kernel.org/pub/software/scm/git/docs/git-commit.html#_discussion">manpage</a>:</p>
  82. <blockquote>
  83. <p>Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, Git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.</p>
  84. </blockquote>
  85. <p>Firstly, 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. For example:</p>
  86. <div class="highlighter-rouge"><pre class="highlight"><code>Fix typo in introduction to user guide
  87. </code></pre>
  88. </div>
  89. <p>Nothing more need be said; if the reader wonders what the typo was, she can simply take a look at the change itself, i.e. use <code class="highlighter-rouge">git show</code> or <code class="highlighter-rouge">git diff</code> or <code class="highlighter-rouge">git log -p</code>.</p>
  90. <p>If you’re committing something like this at the command line, it’s easy to use the <code class="highlighter-rouge">-m</code> option to <code class="highlighter-rouge">git commit</code>:</p>
  91. <div class="highlighter-rouge"><pre class="highlight"><code>$ git commit -m"Fix typo in introduction to user guide"
  92. </code></pre>
  93. </div>
  94. <p>However, when a commit merits a bit of explanation and context, you need to write a body. For example:</p>
  95. <div class="highlighter-rouge"><pre class="highlight"><code>Derezz the master control program
  96. MCP turned out to be evil and had become intent on world domination.
  97. This commit throws Tron's disc into MCP (causing its deresolution)
  98. and turns it back into a chess game.
  99. </code></pre>
  100. </div>
  101. <p>Commit messages with bodies are not so easy to write with the <code class="highlighter-rouge">-m</code> option. You’re better off writing the message in a proper text editor. If you do not already have an editor set up for use with Git at the command line, read <a href="https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration">this section of Pro Git</a>.</p>
  102. <p>In any case, the separation of subject from body pays off when browsing the log. Here’s the full log entry:</p>
  103. <div class="highlighter-rouge"><pre class="highlight"><code>$ git log
  104. commit 42e769bdf4894310333942ffc5a15151222a87be
  105. Author: Kevin Flynn &lt;kevin@flynnsarcade.com&gt;
  106. Date: Fri Jan 01 00:00:00 1982 -0200
  107. Derezz the master control program
  108. MCP turned out to be evil and had become intent on world domination.
  109. This commit throws Tron's disc into MCP (causing its deresolution)
  110. and turns it back into a chess game.
  111. </code></pre>
  112. </div>
  113. <p>And now <code class="highlighter-rouge">git log --oneline</code>, which prints out just the subject line:</p>
  114. <div class="highlighter-rouge"><pre class="highlight"><code>$ git log --oneline
  115. 42e769 Derezz the master control program
  116. </code></pre>
  117. </div>
  118. <p>Or, <code class="highlighter-rouge">git shortlog</code>, which groups commits by user, again showing just the subject line for concision:</p>
  119. <div class="highlighter-rouge"><pre class="highlight"><code>$ git shortlog
  120. Kevin Flynn (1):
  121. Derezz the master control program
  122. Alan Bradley (1):
  123. Introduce security program "Tron"
  124. Ed Dillinger (3):
  125. Rename chess program to "MCP"
  126. Modify chess program
  127. Upgrade chess program
  128. Walter Gibbs (1):
  129. Introduce protoype chess program
  130. </code></pre>
  131. </div>
  132. <p>There are a number of other contexts in Git where the distinction between subject line and body kicks in—but none of them work properly without the blank line in between.</p>
  133. <h3 id="limit-50">2. Limit the subject line to 50 characters</h3>
  134. <p>50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what’s going on.</p>
  135. <blockquote>
  136. <p><em>Tip: If you’re having a hard time summarizing, you might be committing too many changes at once. Strive for <a href="https://www.freshconsulting.com/atomic-commits/">atomic commits</a> (a topic for a separate post).</em></p>
  137. </blockquote>
  138. <p>GitHub’s UI is fully aware of these conventions. It will warn you if you go past the 50 character limit:</p>
  139. <p><img src="https://i.imgur.com/zyBU2l6.png" alt="gh1"/></p>
  140. <p>And will truncate any subject line longer than 72 characters with an ellipsis:</p>
  141. <p><img src="https://i.imgur.com/27n9O8y.png" alt="gh2"/></p>
  142. <p>So shoot for 50 characters, but consider 72 the hard limit.</p>
  143. <h3 id="capitalize">3. Capitalize the subject line</h3>
  144. <p>This is as simple as it sounds. Begin all subject lines with a capital letter.</p>
  145. <p>For example:</p>
  146. <ul>
  147. <li>Accelerate to 88 miles per hour</li>
  148. </ul>
  149. <p>Instead of:</p>
  150. <ul>
  151. <li>accelerate to 88 miles per hour</li>
  152. </ul>
  153. <h3 id="end">4. Do not end the subject line with a period</h3>
  154. <p>Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you’re trying to keep them to <a href="#limit-50">50 chars or less</a>.</p>
  155. <p>Example:</p>
  156. <p>Instead of:</p>
  157. <h3 id="imperative">5. Use the imperative mood in the subject line</h3>
  158. <p><em>Imperative mood</em> just means “spoken or written as if giving a command or instruction”. A few examples:</p>
  159. <ul>
  160. <li>Clean your room</li>
  161. <li>Close the door</li>
  162. <li>Take out the trash</li>
  163. </ul>
  164. <p>Each of the seven rules you’re reading about right now are written in the imperative (“Wrap the body at 72 characters”, etc.).</p>
  165. <p>The imperative can sound a little rude; that’s why we don’t often use it. But it’s perfect for Git commit subject lines. One reason for this is that <strong>Git itself uses the imperative whenever it creates a commit on your behalf</strong>.</p>
  166. <p>For example, the default message created when using <code class="highlighter-rouge">git merge</code> reads:</p>
  167. <p>And when using <code class="highlighter-rouge">git revert</code>:</p>
  168. <div class="highlighter-rouge"><pre class="highlight"><code>Revert "Add the thing with the stuff"
  169. This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.
  170. </code></pre>
  171. </div>
  172. <p>Or when clicking the “Merge” button on a GitHub pull request:</p>
  173. <div class="highlighter-rouge"><pre class="highlight"><code>Merge pull request #123 from someuser/somebranch
  174. </code></pre>
  175. </div>
  176. <p>So when you write your commit messages in the imperative, you’re following Git’s own built-in conventions. For example:</p>
  177. <ul>
  178. <li>Refactor subsystem X for readability</li>
  179. <li>Update getting started documentation</li>
  180. <li>Remove deprecated methods</li>
  181. <li>Release version 1.0.0</li>
  182. </ul>
  183. <p>Writing this way can be a little awkward at first. We’re more used to speaking in the <em>indicative mood</em>, which is all about reporting facts. That’s why commit messages often end up reading like this:</p>
  184. <ul>
  185. <li>Fixed bug with Y</li>
  186. <li>Changing behavior of X</li>
  187. </ul>
  188. <p>And sometimes commit messages get written as a description of their contents:</p>
  189. <ul>
  190. <li>More fixes for broken stuff</li>
  191. <li>Sweet new API methods</li>
  192. </ul>
  193. <p>To remove any confusion, here’s a simple rule to get it right every time.</p>
  194. <p><strong>A properly formed Git commit subject line should always be able to complete the following sentence</strong>:</p>
  195. <ul>
  196. <li>If applied, this commit will <em><u>your subject line here</u></em></li>
  197. </ul>
  198. <p>For example:</p>
  199. <ul>
  200. <li>If applied, this commit will <em>refactor subsystem X for readability</em></li>
  201. <li>If applied, this commit will <em>update getting started documentation</em></li>
  202. <li>If applied, this commit will <em>remove deprecated methods</em></li>
  203. <li>If applied, this commit will <em>release version 1.0.0</em></li>
  204. <li>If applied, this commit will <em>merge pull request #123 from user/branch</em></li>
  205. </ul>
  206. <p>Notice how this doesn’t work for the other non-imperative forms:</p>
  207. <ul>
  208. <li>If applied, this commit will <em>fixed bug with Y</em></li>
  209. <li>If applied, this commit will <em>changing behavior of X</em></li>
  210. <li>If applied, this commit will <em>more fixes for broken stuff</em></li>
  211. <li>If applied, this commit will <em>sweet new API methods</em></li>
  212. </ul>
  213. <blockquote>
  214. <p><em>Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.</em></p>
  215. </blockquote>
  216. <h3 id="wrap-72">6. Wrap the body at 72 characters</h3>
  217. <p>Git never wraps text automatically. When you write the body of a commit message, you must mind its right margin, and wrap text manually.</p>
  218. <p>The recommendation is to do this at 72 characters, so that Git has plenty of room to indent text while still keeping everything under 80 characters overall.</p>
  219. <p>A good text editor can help here. It’s easy to configure Vim, for example, to wrap text at 72 characters when you’re writing a Git commit. Traditionally, however, IDEs have been terrible at providing smart support for text wrapping in commit messages (although in recent versions, IntelliJ IDEA has <a href="https://youtrack.jetbrains.com/issue/IDEA-53615">finally</a> <a href="https://youtrack.jetbrains.com/issue/IDEA-53615#comment=27-448299">gotten</a> <a href="https://youtrack.jetbrains.com/issue/IDEA-53615#comment=27-446912">better</a> about this).</p>
  220. <h3 id="why-not-how">7. Use the body to explain what and why vs. how</h3>
  221. <p>This <a href="https://github.com/bitcoin/bitcoin/commit/eb0b56b19017ab5c16c745e6da39c53126924ed6">commit from Bitcoin Core</a> is a great example of explaining what changed and why:</p>
  222. <div class="highlighter-rouge"><pre class="highlight"><code>commit eb0b56b19017ab5c16c745e6da39c53126924ed6
  223. Author: Pieter Wuille &lt;pieter.wuille@gmail.com&gt;
  224. Date: Fri Aug 1 22:57:55 2014 +0200
  225. Simplify serialize.h's exception handling
  226. Remove the 'state' and 'exceptmask' from serialize.h's stream
  227. implementations, as well as related methods.
  228. As exceptmask always included 'failbit', and setstate was always
  229. called with bits = failbit, all it did was immediately raise an
  230. exception. Get rid of those variables, and replace the setstate
  231. with direct exception throwing (which also removes some dead
  232. code).
  233. As a result, good() is never reached after a failure (there are
  234. only 2 calls, one of which is in tests), and can just be replaced
  235. by !eof().
  236. fail(), clear(n) and exceptions() are just never called. Delete
  237. them.
  238. </code></pre>
  239. </div>
  240. <p>Take a look at the <a href="https://github.com/bitcoin/bitcoin/commit/eb0b56b19017ab5c16c745e6da39c53126924ed6">full diff</a> and just think how much time the author is saving fellow and future committers by taking the time to provide this context here and now. If he didn’t, it would probably be lost forever.</p>
  241. <p>In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if the code is so complex that it needs to be explained in prose, that’s what source comments are for). 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.</p>
  242. <p>The future maintainer that thanks you may be yourself!</p>
  243. <h2 id="tips">Tips</h2>
  244. <h3 id="learn-to-love-the-command-line-leave-the-ide-behind">Learn to love the command line. Leave the IDE behind.</h3>
  245. <p>For as many reasons as there are Git subcommands, it’s wise to embrace the command line. Git is insanely powerful; IDEs are too, but each in different ways. I use an IDE every day (IntelliJ IDEA) and have used others extensively (Eclipse), but I have never seen IDE integration for Git that could begin to match the ease and power of the command line (once you know it).</p>
  246. <p>Certain Git-related IDE functions are invaluable, like calling <code class="highlighter-rouge">git rm</code> when you delete a file, and doing the right stuff with <code class="highlighter-rouge">git</code> when you rename one. Where everything falls apart is when you start trying to commit, merge, rebase, or do sophisticated history analysis through the IDE.</p>
  247. <p>When it comes to wielding the full power of Git, it’s command-line all the way.</p>
  248. <p>Remember that whether you use Bash or Zsh or Powershell, there are <a href="https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Bash">tab</a> <a href="https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Zsh">completion</a> <a href="https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Powershell">scripts</a> that take much of the pain out of remembering the subcommands and switches.</p>
  249. <h3 id="read-pro-git">Read Pro Git</h3>
  250. <p>The <a href="https://git-scm.com/book/en/v2">Pro Git</a> book is available online for free, and it’s fantastic. Take advantage!</p>