emiel.github.io/on-commit-messages.html at main · emiel/emiel.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="https://blog.ttyout.net/theme/css/main.css">
  <title>On Commit Messages | Galloping Alligator</title>

  <meta name="author" content="Emiel van de Laar">
  <meta name="description" content="Most if not all version control systems allow for annotating a change with a descriptive message. On many occasions, I&#39;ve needed to convince others that this is a fantastic feature that should be taken advantage of. Here&#39;s my take on the matter …">
</head>

<body class="site-container">

<header class="site-header">
  <h1><a href="https://blog.ttyout.net/">Galloping Alligator</a></h1>

  <nav class="top-nav">
      <a href="/">Writing</a>
      <a href="/pages/about.html">About</a>
      <a href="/pages/uses.html">Uses</a>
  </nav>
</header>

<main class="site-content">
  <article>
    <header>
      <h2>On Commit Messages</h2>
      <small>
        <em>
        Posted on <time datetime="2021-03-19T17:00:00+01:00">2021-03-19</time>
        </em>
      </small>
    </header>

    <div class="article-content">
      <p>Most if not all version control systems allow for annotating a change with a
descriptive message. On many occasions, I've needed to convince others that
this is a fantastic feature that should be taken advantage of. Here's my take
on the matter.</p>
<div class="section" id="why-write-messages-at-all">
<h2>Why write messages at all?</h2>
<p>Here's why:</p>
<ul class="simple">
<li><strong>Context</strong>: A well-written commit message is the best way to communicate
valuable context about a change to other project contributors, and indeed, to
your future self. By first reading the commit message the reader should have
enough of an introduction and/or understanding to be able to grasp the code
changes that follow.</li>
<li><strong>Collaboration</strong>: Without any kind of introduction to the change, other
contributors need to track you down to retrieve it. We should be considerate
and spare them the effort. If more in-depth details are required they will
track you down anyway. ;) Besides you're collaborating here and this is a
great opportunity to share some knowledge.</li>
<li><strong>History</strong>: Any kind of &quot;real world&quot; project will accumulate a fair amount
of history via other contributors. For anyone joining the project at a later
time, the commit history can tell a valuable story if decent commit messages
have been written. There can be real value here. &quot;Uhm, why was it done like
that? (git log) Ah, I see!&quot;</li>
</ul>
<p>So go ahead and take a few minutes to compose a message. Your readers
(including yourself) will be better off. ;) If you need more convincing, &quot;<a class="reference external" href="https://dhwthompson.com/2019/my-favourite-git-commit">My
favourite Git commit</a>&quot;, is one of my favorite posts on this subject.</p>
</div>
<div class="section" id="what-should-i-write">
<h2>What should I write?</h2>
<p>What you should write depends on the change you are introducing. You should
judge for yourself how much detail to include; just keep your reader in mind.</p>
<ul class="simple">
<li>Write at the very least a decent subject line. Messages like &quot;WIP&quot; (work in
progress) are fine for your topic branches but should be updated before the
change lands in the &quot;main/master&quot; branch.</li>
<li>Go ahead and summarize the change made so the reader knows what they are
looking at. If you find your message is getting a bit long it may be a sign
you need to break up the change into smaller chunks, i.e. multiple commits.</li>
</ul>
<p>Let's go ahead and cover some common changes:</p>
<ul class="simple">
<li><strong>Functional change</strong>: Provide motivation for the change and convey intent.
Why are these changes needed? What issue does it solve? What is the added
value? This is especially important in production code. Also, a reference to
a related discussion, i.e. issue tracking system, will be appreciated.</li>
<li><strong>Hairy bug fix</strong>: You spent an insane amount of time tracking down a nasty
bug. Go ahead and document the funky behavior in the change as a comment
instead of including your full war-story in the commit message. When
revisiting the code the adjacent comment will likely be spotted but the
commit message won't.</li>
<li><strong>Spelling correction</strong>: A single line subject will suffice. Don't go
overboard.</li>
</ul>
</div>

    </div>
  </article>
</main>

<footer class="site-footer">
<nav>
    <a href="https://github.com/emiel" ref="me">GitHub</a>
    <a href="https://hachyderm.io/@emiel" ref="me">Mastodon</a>
    <a href="mailto:gemiel@gmail.com" ref="me">e-mail</a>
  </nav>
  <p class="copyright">&copy; 2014&ndash;2025 Emiel van de Laar</p>
</footer>

</body>
</html>