What a good commit message looks like (2011) | Hacker News Reader

What a good commit message looks like (2011)

github.com

96 pointsziodave95 comments

        The body of the commit message can be several paragraphs, and
	please do proper word-wrap and keep columns shorter than about
	74 characters or so. That way "git log" will show things
	nicely even when it's indented.

Software should help me, I shouldn't have to help it. Why doesn't git handle this formatting automatically? I shouldn't need to manually break lines for typographical (not paragraph) reasons.

That software is called a text editor and you can configure it to do the text wrapping for you.

More seriously, it is quite hard to wrap text correctly after you submitted it. For example people add manual line breaks for structuring text and to separate things like quoted commands from the rest. It would be much more cumbersome to go back after a git commit to fix this, probably in multiple iterations until you get the intended presentation instead of just doing it right from the start.

Web browsers line break text dynamically just fine - as do, well, text editors.

Using a text editor to automatically embed line breaks doesn't fix the problem: embedding line breaks in text for formatting is wrong semantically. Hard line breaks should mean something. Now I can't reflow the text to display it on a web page in a normal font, because I can't be sure of which line breaks are meaningful, and which are formatting.

Except now you need everything to handle textual contexts because while I do want my nice paragraph of text to be wrapped, I don't want my code snippet to be wrapped at all, and I want my nested list to be correctly intended at wrapping.

Is there not precedent for handling that

    correctly in a plain text field?

Which, in the case of HN and other pages, can either break the formatting of the entire page by pushing the right margin beyond the window, or artificially constrained windows which you need to scroll sideways on.

Text layout is a hard problem. It's why TEX (and its derivatives) is still so damned useful (and complicated).

It's really not that hard in this case.

Don't wrap lines with a four-space prefix (or whatever format is decided), wrap lines without one. Allow users to disable the wrapping if they prefer wrapped code. The prefix can be stripped at display time if you wish, so that code is left-aligned - actually, since the formatting isn't encoded in the log, only the semantics, users can configure the display as they please.

Possible handle lines beginning with - as lists and indent them correctly. If a message somehow breaks the format, do not accept it. This isn't TeX-level complexity.

I guess we want to use markdown in commit messages then.

That provides absolutely no help. Markdown-formatted messages doesn't give you a plain-text renderer and text layout engine.

OPs point remains. It's git's job to tell me its limitations. Not my job to adapt my tools to it.

When practical, of course.

In this case, git could simply give a "are you sure you want to commit with these long lines?" warning.

Git copes just fine with long commit messages. Providing the rest of your team is happy with it and your tools can display it ok, just do it.

Agreed. My last two jobs had no line length limit on commit messages (or code) and it was great. But culturally, C# developers don't live in an 80-column terminal window, either.

m-X auto-fill-mode. You can add this to other modes automatically. I almost always have it on.

Added to Emacs in 1977.

The point is that people shouldn't be littering their text with hard line breaks just to support software that can't do word-wrapping properly. That your editor can do this doesn't mean you should. It might make the text look a bit prettier in an 80 column terminal, but it makes it worse pretty much anywhere else.

> The point is that people shouldn't be littering their text with hard line breaks just to support software that can't do word-wrapping properly.

How can the software guess whether a given line should be wrapped (text), should not be wrapped (code), should be wrap-indented (list item) or should be wrap-prefixed (quote block) when it's only given raw bytes assumed to be text without further information?

>should not be wrapped (code)

I'm not sure why this matters much?

If the code doesn't fit on the screen you're viewing it on, then it's not going to be convenient to read regardless of whether you wrap it or have a horizontal scroll.

>should be wrap-indented

When would you have an indented line that shouldn't be wrap-indented?

> I'm not sure why this matters much?

Because wrapped code is generally nonsensical.

> If the code doesn't fit on the screen you're viewing it on, then it's not going to be convenient to read

Inconvenient is one thing, nonsensical is an other.

> When would you have an indented line that shouldn't be wrap-indented?

That's noted right after, in the parens: list items.

This is not correct wrapping for a list item:

    * this is a list
    item

this is correct wrapping for a list item:

    * this is a list
      item

If the display software does not do that (and I'm reasonably certain most would not) I'd much rather properly hard-wrap my text before committing it, that way I know that it will end up correctly wrapped and actually readable.

>Because wrapped code is generally nonsensical.

Not really? It's probably slightly more awkward to read than scrolling, but then, the solution is to read code on an appropriately sized screen in the first place.

And incidentally, truncated code definitely is nonsensical.

>List items.

They can be handled as you mention, but it's hardly the worst thing in the world if they're not.

And if you really care about formatting this much, you should use a format that encodes it properly (e.g. Markdown) instead of producing the text equivalent of a PDF.

> Not really?

Yes really.

> but then, the solution is to read code on an appropriately sized screen in the first place.

That's not a solution to anything.

> And incidentally, truncated code definitely is nonsensical.

Truncated code is visibly truncated, not nonsensical garbage right next to actual code.

> They can be handled as you mention

And the software knows what a list item is… how?

> it's hardly the worst thing in the world if they're not.

One more fantastic non-solution to listed problems, we're definitely going places.

> And if you really care about formatting this much, you should use a format that encodes it properly (e.g. Markdown) instead of producing the text equivalent of a PDF.

So you're saying git should embed a markdown renderer and text layout engine?

>That's not a solution to anything.

I'm not sure what scenario you're imagining where you absolutely have to read code in commit messages on an unreasonably narrow screen, and you can't wait until you have an appropriate machine. But if a scenario occurred where that were important, I'm sure you'd manage to read some wrapped code, it's not that hard.

>Truncated code is visibly truncated

Unless it's not, because there's ` + someExtraStuff` just off the end.

>So you're saying git should embed a markdown renderer and text layout engine?

If you really want pristinely formatted commit messages that badly then yes.

> If you really want pristinely formatted commit messages that badly then yes.

Mate, I already have pristinely formatted commit messages, because I format them as I desire.

You are the person telling me I shouldn't be formatting my messages and a nebulous "software" ought do that, the burden's on you to give them the tools which yield the same pristinely formatted output I already achieve without a formatted input.

You have pristinely formatted commit messages when viewed in ~80 column monospace, but poorly formatted commit messages anywhere else.

The word "generally" here has a precise meaning when used in a formal (mathematical) sense. Using that meaning, the phrase "wrapped code is generally nonsensical" could be read as "there exists some code that is nonsensical when line-wrapped" or "the amount of code that is nonsensical when line-wrapped is non-zero". More precisely, it means that, in general, you cannot rely on any ol' code to remain sensical after wrapping has taken place. Hopefully, it's obvious that this is true.

Markdown renderers seem perfectly capable of this. git wouldn't even need to disambiguate asterisk for lists vs. asterisk for emphasis.

So every piece of software now needs a markdown renderer?

If Linus wants a consistent commit message format, he should enforce it at the software level, rather than hoping people read a comment he left in a repository about logging his swimming information.

This does not mean that the format needs to be Markdown (which includes embedded HTML, so obviously not Markdown), or that all software needs a Markdown renderer. I'm not sure why you'd conclude that.

Enforcing is an administrative task committed by specific people in specific projects (there is a thing called 'best practice', but it never is a hard rule). Tools authors should not enforce anything, it's not their job, responsibility and competence, even if a particular project like Linux has the same Linus for both project management / rcs tool writing.

we don't even need markdown. Groff and less are already there and already handle formatting and reflowing just fine.

Groff is a text processing/formatting system so same issue, and less doesn't handle jack shit.

Except that almost every time, I am composing and viewing the log messages from a terminal. The logical thing for a web page to do is to display logs as “preformatted” text (because they are, same as code).

It would be interesting to have a way to indicate a formatting style when composing a log message though; for instance, a way to indicate that a log contains Markdown code.

On the other hand, non-terminal people should not use terminal-oriented software along with flowing text ideology. We do not even distinguish line breaks / paragraph breaks for now (though we often emulate that via \n\n). We do not have add-indent-level and cut-indent-level character codes for to not mess with indent. Markdown may seem good, but it is still low-level format, like rtf or html; it isn't natural in any way. We just pretend that good old-and-new Unix tools are perfectly applicable to modern textual fashion, when they really aren't.

That said, it is arguable if we must do that step forward from the development perspective. These tools already solved real issues, and now we discuss preferences. Personally, I'm fine with terminal on the left and wrap-capable editor on the right. It's not "to support software", I really like it more.

auto-fill mode doesn't reflow paragraphs at will, it just inserts a line break when you go over the limit.

For instance, if you're editing a document and write a long sentence, that spreads over 3-4 lines. You then take a scalpel to it to make it more concise, so that it fits on a line or 2. Emacs won't reflow it automatically, you can manually get it to reflow (M-q by default), but its not the behaviors you expect from say a word processing program. Same exists if you insert new text.

TLDR: all auto-fill mode does is insert new lines when you reach the line length limit.

Pardon me for piggy-backing on your comment, but the Vim equivalent of Emacs's auto-fill mode is to `:set textwidth=74 wrap linebreak` (where 74 here is the column at which to wrap, and `linebreak` tells Vim to break at some character specified in `breakat`, which is set to a useful default consisting of whitespace and various punctuation). The default behavior is the same as @compsciphd describes for Emacs: it won't reflow automatically during editing, however, the sequence `gqap` in command mode will reflow the current paragraph (`gq` is a command to format text, and it is followed by a motion to specify the text to format: in this case `ap` is the motion for "a paragraph", i.e., the paragraph which currently contains the cursor).

Vim also has an auto-format feature, which can be enabled with `:set formatoptions+=a` and will make paragraph editing behave a bit more like, say, a word processing program, but the Vim help file cautions that formatting long paragraphs or paragraphs with complicated indentation can get slow. I haven't really used the auto-format feature myself, so I can't comment on how slow it actually seems to be in practice.

Translation: I won't want to do the extra work to format my commit messages.

How I understand that: If you can't format your commit messages, how can you be considered reliable to format your code how the company defines it?

I'm sure someone can write a patch for git commit comments to enforce a 74 character limit on line width with CR\LF indiscriminately or separate them "smarter" by breaking words at 0020 after it crosses the 74 character width limit. But that's besides the point.

>Translation: I won't want to do the extra work to format my commit messages.

Patient: "It hurts when I move my arm".

Doctor: Don't move your arm.

It's absurd to take a principled stand against software alleviating development pain.

It's absurd to take a principled stand against software alleviating development pain.

lolwut? Is anyone saying: "don't write a commit-msg hook!" or "how dare you configure a programmer's editor to wrap at a fixed width?"

I see a lot of what boils down to: "it's not my problem how you and your teams go about following a formatting standard that's popular but not mandatory."

Tools that handle formatting for you are a productivity multiplier and not having them but enforcing a specific style is wasteful.

> but enforcing a specific style is wasteful

Tell that to the plentiful amount of businesses and software development groups that enforcing good coding style is wasteful. I'll wait.

Why did you only quote part of that sentence?

> How I understand that: If you can't format your commit messages, how can you be considered reliable to format your code how the company defines it?

This is a classic form of non sequitur. This kind of logic is the driver behind "If you can't be arsed to dress up in a suit and tie then you don't really care about your job" and "If you don't support our troops you are a Bad Person and you should leave the country".

Empirically, no one has shown formatting git commit messages to be predictive of code quality whatsoever. Sure, good engineers tend toward longer, more descriptive commits, but whether or not they follow proper text wrapping is totally beside the point. Poor code formatting is indicative of lack of skill, poor commit message formatting is indicative of a lack of knowledge of this one web page that most people have probably never seen.

emacs magit tells me the commit message is too long when I exceed one line. Something seems wrong...

It's probably trying to tell you to leave a blank line between the title and the body of the message.

Just for those who are tired of sites that disable both 2tap-zoom and 'pre' block wrapping on mobile.

---

A good commit message looks like this:

Header line: explaining the commit in one line

Body of commit message is a few lines of text, explaining things in more detail, possibly giving some background about the issue being fixed, etc etc.

The body of the commit message can be several paragraphs, and please do proper word-wrap and keep columns shorter than about 74 characters or so. That way "git log" will show things nicely even when it's indented.

Reported-by: whoever-reported-it

Signed-off-by: Your Name <youremail@yourhost.com>

where that header line really should be meaningful, and really should be just one line. That header line is what is shown by tools like gitk and shortlog, and should summarize the change in one readable line of text, independently of the longer explanation.

Recently, I try to write the first line of my commit messages so they describe what the system now does, compared to before the commit. This makes reading the history much more fun. Like:

    Validation of email addresses now sends a test email to the user, instead of the old regex that never worked.

This style does not work for all kinds of changes, but when it works, it creates a nice history of how the functionality of the system grew...

Looks too long to me, will end up looking bad in most things.

Including the old bit is meaningless noise there.

I'd use something like "Improve email validation" or "email: send a test email as validation" or such.

The body is where you can describe previous behaviour and give more details.

Yeah that. I'd have it describe what the commit does in the subject, and both the why and how in the body:

Validation of email addresses now sends a test email to the user, instead of the old regex that never worked.

> Send test email to user for email address validation > > This change was done because the old regex never worked; see also {link} and {link} for more information.

as an example. Ideally the header also contains a hint to the module the change was done in, etc. The linux kernel commits take this to (what comes across to me as) the highest levels.

Here's what, Tim Pope, our favourite vim nerd has to say about this: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa... (Same, but with more words.)

A point of contention seems to be the choice of the imperative, at least for the subject line. While I'm really used to it, both when reading and writing, many people seem to strongly prefer past tense ("Fixed bug …" instead of "Fix bug …").

With that one, the way I see it is that when people use the past tense, the git history becomes a work log, i.e. what the committer did; "I fixed bug...". It shouldn't be like that, the commit should describe what the commit does, i.e. "Fix bug" or "Fixes bug". the latter uses more letters though, which is probably why I see a preference for the "Fix bug" format due to the (soft) 50 character subject constraint.

I am wary of agreeing with someone with your uname but I have to agree! Go with the project's style, but best is if that style is about the code itself.

I don't care if this was easy or hard or the bug was non-obvious or if you used a weird trick.

I do care what the change does: fixes a race condition, adds a new file mode etc. Those changes matter at the time (what's new in the code?) and when looking backwards (ah, here's where that new file mode was added, let's see what was going on then).

Also, when using his amazing git plugin (fugitive) to commit you get very useful highlighting when you break these conventions.

http://i.imgur.com/8ix5JGa.png

More importantly, the correct way is the way that is currently being used.

If the project uses past tense, use it. If you want to change the convention, that's okay too, but everyone has to change.

It's exactly the same issue as coding style. If you can look at code or commit messages and figure out who wrote it based purely on style/formatting, you're doing it wrong (or rather: the person using the inconsistent style/format is).

Tenses in commit messages seem a bit pedantic and inconsequential. It doesn't really affect much. Unlike tabs vs. spaces, where mixing would cause a mess.

Most code formatting issues are pedantic and inconsequential. Never stopped us from fighting to the death about them ;)

I open an issue for every feature, bug or enhancement, then I mention the issue in the commit followed by a short description of the changes. I wrote down a procedure that I follow for every commit [1].

This allows me to keep the commit line short and to see the commits history related to the resolution of a bug or feature.

When using Gitlab, Bitbucket or Github the issues and the commits are cross-linked (example: [0]).

[0] https://bitbucket.org/binarno/imebra/issues/162/ [1] https://imebra.com/wp-content/uploads/documentation/html/sop...

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

I think that on the contrary, everything should be in the commit. The commit message is dated, it has an author and a context. How often do you come across stray comments which shouldn't be here because the code got refactored away? Commis are often just a git blame away anyway.

Except when a line has been changed over a longer period of time. Although maybe I'm just not comfortable with tracking history too much, because in the applications I generally work on (customer-facing webapps) we generally don't need to look back in history too much.

Also: avoid using comments where proper names would suffice:

  // cleans responses
  function zrgfy(response){
    ...
  }

should be something like:

  function cleanResponse(response){
    ...
  }

My rule of thumb in commenting is that I comment the why or how, not the what... Unless the what is sufficiently non-obvious, in which case it is usually prudent to have a really good explanation of the why, as well.

Highly disagree. As long as the code lives, the commit lives.

until the git killer comes along and the team decides how much history they are willing to migrate. I've seen it happen every 5(?) years across several companies. Ironically it's always the oldest commit messages that turn out to be the most valuable because newer changes people remember

What is "The Git Killer"?

That's just a generic stand-in for any new version control system that becomes popular enough to display Git. For example, Pijul (https://pijul.org), although Pijul specifically won't become popular because it's licensed under AGPL3.

yep as telo.. said - whatever will inevitably supercede git. In my own work it was VSS > Perforce > svn > git

All of those were good choices when they were new, and suboptimal choices when the next better solution came along.

I had the feeling companies would just stick to their thing.

Last I worked with used CVS and always talked about switching to SVN, but never did.

We have CVS, SVN, a legacy internal tool for managing git repos and most recently, Bitbucket. And some of these repos go back years. So companies do migrate version control systems.

A commit doesn't suffer from the same bit rot as a comment. Descriptions of how code changes doesn't shift as much as description of how code operates. If git blame, git log, and git diff are part of your workflow finding a git commit describing a piece of code is easy.

The commit message is frequently the only comment that ties the set of changes together so it is a good place to describe the change as a whole. This is not always clear when looking at any particular function, for example.

Great system about our commit system at work is that every commit starts with the name of a ticket of our ticket system (jira) so you can go back to that ticket whenever that commit comes up anywhere and understand the commit better

even better systems allows to link tickets to commits.

Not the OP, but our JIRA instance does this. From a ticket in JIRA, you can see any commits, branches or pull requests mentioning that ticket.

We also use this convention with gitflow, so our branches are named eg, feature/PROJ-1234-added-new-ui or bug/PROJ-2345-fix-new-ui. This also lets JIRA find and link them, and makes pull requests get the ticket number in their title by default as well (since its based on branch name).

The last bit is just a short human-readable thing to make branches easier to look at and find, because the initial way we started using gitflow:

    feature/
      feature/PROJ-2286
      feature/PROJ-2352
      feature/PROJ-2367
      feature/PROJ-2382
      feature/PROJ-2385
    bug/
      bug/PROJ-2240
      bug/PROJ-2323
      bug/PROJ-2393

is completely unintelligible.

For those who aren't familiar with the kernel process, what's the Reported-by line? Simply the reporter of any original bug that the patch was written to fix?

I understand that the Signed-off-by line is equivalent to a CLA, right?

Yes and yes.

Yes, and many of the maintainer automations will email the reporter about the patch being merged into the various releases.

And signed-off-by is essentially a shorthand for agreement to this document: http://developercertificate.org/

Yes, Reported-by is the original reporter.

Signed-off-by is fallout from the SCO lawsuit. It has nothing to do with agreeing to any sort of CLA; it's just another way to confirm that the code was written by the person in Signed-off-by, or that the person in Signed-off-by thinks it was created under appropriate open source conditions (e.g. the company who paid the developer to write it is okay with it being released).

Nice. At an old job, I got a little bored, so I'd spend time crafting wonderful commit messages. Most of them contained puns, some very subtle, some less so.

In regards to commit ethos, I'm not sure I agree with all of the statements made. To me, something simple/concise, that others will understand, but not lacking in key info, is much better than several paragraphs explaining the same thing.

This is still relevant, as my friend Cesar wrote about it just the other day (with a very similar title) » https://hackernoon.com/what-makes-a-good-commit-message-995d...

One problem with this is that git gets used as a deployment tool as well as a version control system.

Trying to get something to run on Heroku involved making lots of small changes just to get things to run on the server the same as on my dev machine.

When you do that 10 or 20 times the commit message become somewhat meaningless.

I also commit like 20 things to get Heroku working properly. But after I am done with that, I `rebase` it into one commit. Then I push it into my `origin/master`, and force push `heroku/master`.

generally when I'm trying this stuff I'll make a new branch to work off of and deploy from that. when I've figured out how it needs to work, I'll squash the commits and merge into master.

The link within that README leading to what "Signed-off-by" means is now broken. Use:

https://gerrit-review.googlesource.com/Documentation/user-si...

I made this git commit template sometime ago. Check it out if it is of any help: https://gist.github.com/adeekshith/cd4c95a064977cdc6c50

don't use git commit messages as "dear diary" sort of things.

For example:

"I fixed the button issue on the homepage. Still, need to center the title."

would be better written as:

"fixes button issue on homepage"

Always think about what that commit does to the codebase. This is obviously for single-line commits. I suppose it would be okay to "dear diary" in the commit body. You can provide rationality or context in the commit body.

My recommended style is:

    Fix button issue on homepage
    
    This allows the title to be centered,
    as the button will no longer collide with it.

Then, in a subsequent commit, center the title and put a reference to this one if you feel it's important, like so:

    Center the title on the homepage
    
    It wasn't previously because it would collide with the button,
    but that was fixed in f00b1f.

My commit messages are (usually) one-line, starting early in the sentence with the focus of the effort, and ending with a clear statement of what happened.

Relevant xkcd https://xkcd.com/1296

I once wrote "commit". A fellow coworker still makes fun of me for that, joking of course.

Url changed from https://gist.github.com/matthewhudson/1475276, which (kind of) points to this.

>74 characters

path dependency is hell of a drug.

People use VMs, print stuff on paper, have 10'' laptops, etc.

if you open a terminal window on mac with any kind of display 1080p, 4k whatever with any resolution you will still get a 80x24 terminal by default. Which is the whole purpose of `git log`. Using it on a terminal / ssh session / whatever.

I use ~80 cols terminal because everything is designed to fit in 80 anyway. More than that and it's just whitespace.

The reason for this is that Git patches are meant to be exchanged over email. Historically email has a line limitation of 80 characters. You are supposed to use less than that to allow insertion of quoting characters in the first columns in replies.

Your email client is supposed to fix this restriction in a completely transparent way. There are a few standards for that, and you can bet every client supports all of them.

Uhm, no, that is not the reality we live in. Things like format=flowed exist, but I would not say that "all" clients support that. For example Apple Mail lately got an obsession for quoted printable encoding with very long lines.

Reply on news.ycombinator.com