Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Commit messages are not titles (2015)

antirez.com

Post reply on HN
Print view View original

1–10 of 58 posts

Re: Commit messages are not titles (2015)

#2

Post by xwdv »

Commit messages are not titles, or subjects, they are COMMANDS, written in the present tense, that describe exactly what will be done to the codebase if you merge in the commit. That’s pretty much all there is to say about it.

Re: Commit messages are not titles (2015)

#3

Post by mcguire »

The first comment:

"Every source control management system has its own rules. So what I say here for Git might not be valid for Mercurial, SVN, Bazaar, ...

"Git has a wonderful tool named format-patch, http://git-scm.com/docs/git..., that takes a commit and converts it to an email, to put it in a nutshell. Why is there a tool for that? Because Git was created to manage Linux kernel development, and that is done in most parts in or around the Linux Kernel Mailing List. So, the entanglement between commits and emails is deep rooted in Git. And yes, the first line of the commit message _is_ used as the subject.

"This explains, why you can google "git commit message" and find the same advice over and over again:

"http://git-scm.com/docs/git...* "https://github.com/erlang/o...* "http://tbaggery.com/2008/04...*

""No dot at the end, because it might end up as email subject, also use 50 chars or less."*

"I agree, that interpreting it as title for a longer commit message is a bad idea. The conciseness of this line is something important to be retained. A well-crafted email subject on the other hand makes in some cases reading the whole email unnecessary or only complimentary. (Yes, such things exist.) And that are the types of commit messages that we should strive for, ending with a dot or not."

Re: Commit messages are not titles (2015)

#5

Post by flafla2 »

caseymarquis wrote: post #4

Commit messages are whatever an individual, community, or organization decides they should be. Debating beyond that is like debating tabs vs spaces. It doesn't matter as long as everyone you're working with is on the same page.

I agree, context is everything. Some commenters here and in the OP argue that there should be no dot at the end because git commit messages are used as the subject of emails. This is of course true in the context of e.g. the linux kernel [1], so the advice makes sense in that context.

But realistically most people today view git through a different client than email, usually github/git CLI. Often, commit messages are the same as PR titles; in that context it makes sense to adopt commits-as-titles. It all comes down to team preference ultimately.

[1] Technically not 100% true these days due to the github mirror

Re: Commit messages are not titles (2015)

#6

Post by awolf »

> If the first line of a commit message is a title, it changes the way you write it. It becomes just some text to introduce some more text, without any stress on the information density.

I agree with the author that commit messages should optimize for information density. However the example they provide does a poor job of this:

> This is a smart synopsis, as information dense as possible.

"This is a" is the type of thing that should never appear in a commit message as it could apply to EVERY commit message. Synopsizing is the action, but doesn't indicate what is being synopsized; one of the most important facts for someone to understand what is happening here. Finally "as information dense as possible", again should also be cut as this is telling us HOW not WHAT (and ironically hurts information density).

Were I writing this example it would be:

  Synopsize how to write a commit message
---

I led an initiative at my current company to enforce all commit messages start with an imperative verb and be less than 72 characters. Some people hate it, some people love it.

Aside from standardization, the primary reason to do this is the imperative mood leads to the most concise sentence possible. By leading with the action, the most natural thing to do next is to talk about what is being acted upon. Unnecessary words are dropped and the most important facts are emphasized. In short it forces the author to get to the point.

  [Act] upon [some aspect of the code]
e.g.

  Add user login link on home screen
  Refactor authentication into separate classes
  Lint PR titles conform to standard format

Re: Commit messages are not titles (2015)

#7

Post by ticmasta »

caseymarquis wrote: post #4

Commit messages are whatever an individual, community, or organization decides they should be. Debating beyond that is like debating tabs vs spaces. It doesn't matter as long as everyone you're working with is on the same page.

Step 1: pick a commit message format.

Step 2: be a dick about it.

Re: Commit messages are not titles (2015)

#8

Post by ticmasta »

xwdv wrote: post #2

Commit messages are not titles, or subjects, they are COMMANDS, written in the present tense, that describe exactly what will be done to the codebase if you merge in the commit. That’s pretty much all there is to say about it.

Well, I'll say more...

They are a summary of what will happen if the commit (which is a bunch of commands) is applied.

They also can elaborate on the context around the commit. It's thoughtful of the commiter if your coworkers don't need to dive into the detailed changes to get a broad picture of why the commit exists.

Post reply on HN