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

41–50 of 58 posts

Re: Commit messages are not titles (2015)

#41

Post by st_goliath »

There is probably no reasonable, generic guide on how to write commit messages, since different communities use git in different ways. So IMO this article is comparable to a discussion about indentation styles or text editors.

> Commit messages are not titles

> Nor subjects, for what matters.

> ...

> however many times there is no body, there is just the first line.

In Linux (the Kernel) development (where git actually came from), commits are sent as patches via e-mail to mailing list for review and for maintainers to pick them up.

The first line from the commit message becomes the subject line, the rest of the commit message and the diff becomes the body of the mail. The commit message should briefly explain why you are doing this, the what should be mostly in the diff itself. Having no body text after the first line for a non-trivial patch would be rather bad practice. Obviously the author of this article comes from a different background.

But then again, in different communities, a concise single line description with a ticket number may be enough.

Re: Commit messages are not titles (2015)

#42

Post by C14L »

awolf wrote: post #6

> 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…

Plus, I like to start with the topic the commit was about, so its easy to scan for a part of the codebase. E.g.

    user/login: Add link on home screen
    auth: Refactor into separate classes

Re: Commit messages are not titles (2015)

#43

Post by pjc50 »

lmm wrote: post #33
protonimitate wrote: post #22

Earlier quoted context omitted.

The "rule" I like when it comes to commit messages it that they should be clear enough that someone who gets woken up for a production issue at 3am can quickly parse what was in the commit and how dangerous it is. Nothings worse than digging through a ton of diffs to find the breaking change.

I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.

Absolutely not! Submitting "derp" to code review is just disrespectful of the reviewer's time.

There's a rationale for every change. The submitter knows it. The reviewer needs to know it. They can try reconstructing it from the diff, which is potentially error prone .. or you could just tell them.

I'll accept "Fix ticket #1234", since that's moved the rationale elsewhere.

Re: Commit messages are not titles (2015)

#44

Post by pjc50 »

Already__Taken wrote: post #39
duxup wrote: post #13

Earlier quoted context omitted.

Seriously, in an interview I was asked about some misc code formatting preferences. At home I use whatever prettier decides. At work I just want to do what everyone else is doing so that we are on the same page. Maybe it is weird or something, I really don't care. More important we all work together.

If AI can write news articles these days I wonder if the actual answer is what you wrote. Build a commit parser into version control to auto-write the titles for you. All you do is write a good message. Prettier but for commit messages.

> Build a commit parser into version control to auto-write the titles for you.

This is like the auto-javadoc software: if the computer can write it from information already in the code, it's a wasteful duplication of time.

Use commit messages and comments for why. Especially if you chose not to do something in a more obvious way for a specific reason. You can't have "self-documenting" for code the version of code that wasn't written.

Re: Commit messages are not titles (2015)

#47

Post by lmm »

em-bee wrote: post #35
lmm wrote: post #33

Earlier quoted context omitted.

I find that requiring "nice" commit messages tends to mean digging through bigger diffs to find the breaking change. If you're fine with commit messages like "fix" or "derp", then people are more willing to make each tiny change a separate commit, and then a git bisect takes you right to the specific diff that caused the problem.

that is an interesting argument, but i don't quite buy it. the commit history is used for other things too, not just to find bugs using bisect. if that was the case we would not need any commit messages in the first place. how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message. the commit message doesn't need to be nice, but it should be d…

> the commit history is used for other things too, not just to find bugs using bisect.

Is it? People assume this, but I'm not convinced they use it for anything else in practice.

> if that was the case we would not need any commit messages in the first place.

I'd be interested in a VCS that followed through on this. Give PRs messages, maybe have some way to attach messages to tags, but permit individual commits to be anonymous.

> how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message.

More effort than writing the change, often enough. In a high-quality codebase the code change should speak for itself. (And if it doesn't, you may well end up needing an explanatory comment in the code anyway).

Re: Commit messages are not titles (2015)

#48

Post by em-bee »

lmm wrote: post #47
em-bee wrote: post #35

Earlier quoted context omitted.

that is an interesting argument, but i don't quite buy it. the commit history is used for other things too, not just to find bugs using bisect. if that was the case we would not need any commit messages in the first place. how much effort does it take to explain the change in a sentence? if it is a small change then it also will be a small commit message. the commit message doesn't need to be nice, but it should be d…

> the commit history is used for other things too, not just to find bugs using bisect. Is it? People assume this, but I'm not convinced they use it for anything else in practice. > if that was the case we would not need any commit messages in the first place. I'd be interested in a VCS that followed through on this. Give PRs messages, maybe have some way to attach messages to tags, but permit individual commits to be…

In a high-quality codebase the code change should speak for itself. (And if it doesn't, you may well end up needing an explanatory comment in the code anyway).

that is indeed pretty much true. in that sense the commit message is just helping me to avoid needing to look at the diff. an outline of the commits.

related to the PR, it would then be interesting to annotate groups of commits. a sequence of commits that make up a PR, but even without depending on the current PR mechanism (which at least in git is not stored anyways, so we need something to fill that gap)

tags don't fit that, as they annotate a single commit, and we'd get to many tags that way. some other mechanism is needed to allow treating a series of commits as a unit.

Re: Commit messages are not titles (2015)

#49

Post by coldtea »

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.

That's an easy copout though.

Sure, commit messages could be mandated to be "whatever an individual, community, or organization decides they should be".

That doesn't mean any of those choices is optimal in absolute terms, or even optimal for the use case of the individual, community, or organization who made the decision.

So it makes sense then to debate what the optimal choice (either absolute, or per use case) is, and this is what the article tries to do.

It would be even better if we had some kind of objective, statistical check on such claims and their pros/cons (e.g. a massive test, with control groups, well defined procedures, and such).

But debating them is also a start, and is needed. If not for anything so that each "individual, community, or organisation" has some input on their decision, and don't just arbitrary impose a format for their commit messages.

Re: Commit messages are not titles (2015)

#50

Post by bagacrap »

reificator wrote: post #19
thrower123 wrote: post #12

Most commit messages look like this: #1234 fixed the fucking fooinater that wouldn't frobulate. Thank god for the hash ticket number linking standard. Unless you are working on the kernel, your context and discussions and notes are in the bugtracker, so there's no very good reason to write an essay in the commit log.

Until you switch bug trackers and the import process subtly mangles that link, and then you switch trackers a few years later and all hope is lost, and then five years after that you hire someone to fix all the bugs that you've been accumulating and they can't tell any of the reasoning behind anything you've done. Are you always going to be on Jira? On Github? When people fork your project are they expected to clone…

Broadly speaking, so much documentation is on the issue tracker, that yes, I expect efforts to be made to preserve that content in perpetuity in one way or another.
Post reply on HN