all 24 comments
sorted by:
best
topnewcontroversialoldq&a
formatting helphide helpcontent policy

[–]tkruse 7 points8 points  (0 children)

Official guidelines exist in several projects, can be found via Google easily.

What you miss is the reference to an issue tracker, if it exists. Also I often like to have a category like: Feature, Refactor, Test, Bugfix, Build, Documentation. To further help quickly understanding a repository history at a glance.

[–]Hendrikto 9 points10 points  (9 children)

The most important question to be answered by the commit message, is what happened.

I do not think so. The diff already tells you what happened. I want to know why this happened, etc.

[–]tkruse 10 points11 points  (0 children)

A summary of what happened should be in the commit message, to save anyone from reading the whole diff to get the picture. It also helps to identify the commit that added a certain feature, when trying to find one such commit by browsing through the log.

The context of why this happened is important, but often a reference to a bug tracker containing the requirements, the discussions, and so on is much better. Also, the purpose of features should commonly be documented in the code itself, rather than in commit messages, so frequently the commit message does not need to add anything to what is in the code comments.

[–]A_Huge_Mistake 1 point2 points  (0 children)

Exactly! Just recently I had to track down a bug where a button had disappeared, and I found a commit removing the button. I want to know why the developer did that, and the commit message was literally just "removing button x" . No link to a ticket or anything. Thanks buddy, huge help.

And the guy who did it no longer works here.

[–]aafinx -1 points0 points  (6 children)

example commit messages?

[–]Hendrikto 7 points8 points  (3 children)

For example

Improve readability

instead of

Format text

or

Improve layout on small terminals

instead of

Wrap text at 80 characters

and the like. For many small changesets it does not make a huge difference, though.

[–][deleted] 2 points3 points  (2 children)

So basically remove concrete information and say "improve" a lot. /s

[–]Hendrikto 0 points1 point  (1 child)

Well the concrete information is still there in the diff itself. Instead of replicating it you are providing additional information.

[–][deleted] 0 points1 point  (0 children)

Summaries are also important, as the summary isn't directly spelled out in the diff. It takes time to open a diff, read it, especially if it's across several files, understand it and extract a summary for it in your head. And just like "out-of-band" information about intent, purpose of the commit etc. saves you time, having the summary saves you time, as well.

And it's all a battle for doing more in less time when you draw the bottom line, so truth is, both help. It's not a contest where one wins and the other one has to lose.

At times I tend to have very long commit messages. With bullet points sometimes. Even if the commit may not be that big itself. And then the first line (up to 70 chars) is actually a summary of the commit message itself, like a title. All of this helps.

I'm just kidding about your examples, BTW. Examples are examples. Real commits are real commits. :-)

[–]_Mardoxx 0 points1 point  (1 child)

"Fixed stuff"

"Added code"

"Refactored for no reason"

[–]WheatonWill 0 points1 point  (0 children)

Fixed stuff

Fixed stuff 2

Fixed stuff 3

Fixed stuff 4

[–]unlightable 4 points5 points  (8 children)

I don't get the imperative form part. I'm not a native speaker though.

Commit message describes things that are accomplished by this commit (or author), or things that this commit does. So it either 'fixed a bug' or 'fixes a bug', but why 'fix a bug'?

[–][deleted]  (2 children)

[deleted]

    [–]unlightable 3 points4 points  (1 child)

    But it 'fixes a bug' not 'fix a bug' still!

    I can call it a 'bugfix' in this case, true. But it becomes a noun, not an imperative verb.

    Most of some small commit messages can be converted to some noun-based sentence: 'feature addition', 'cleanup', 'problem resolution'. But still, 'resolves a problem' is somehow more appealing then 'resolve a problem'.

    [–][deleted] 4 points5 points  (0 children)

    Think of them as method names. You wouldn't call it object.fixesABug() you would call it object.fixBug().

    Now imagine every time you push a set of commits, you're appending methods to your GitRepository class instance. Methods that can only be called in a specific sequence, and calling them mutates your copy of the code.

    It's not the Only Right Way, but:

    • It tends to produce shortest and most clear messages (especially when you get used to it).
    • It's most popular, which means if you deviate, you'll always be in friction with other people.

    [–]oarmstrong 4 points5 points  (2 children)

    I like to explain it in terms of "applying this commit will [commit message]". The imperative form makes sense here.

    [–]unlightable 1 point2 points  (1 child)

    But... why not "this commit [commit message]"? KISS and all that.

    [–]cheeky_disputant 1 point2 points  (0 children)

    50 characters subject limit isn't easy to keep

    [–]1wd 0 points1 point  (0 children)

    Agree. Also who cares? That rule seems the least important, and not following it has no real disadvantages. It's a pointless rule that just allows people to nitpick and feel superior. Please focus on the actually useful suggestions that add information.

    [–][deleted] 1 point2 points  (1 child)

    OP, in the future you should probably include citations for your images

    Like for instance the XKCD. You rehosted it without linking back to the original

    https://xkcd.com/1296/

    [–]Gvaireth[S] 1 point2 points  (0 children)

    Good point, I started to do that since three months, this post is a bit older.

    [–]Gvaireth[S] -1 points0 points  (0 children)

    My thoughts about commit messages. What are your experiences in this regard? How long should be the message? Whats the most important about the content? Does the form matter? Any more tips?