Commit messages are not titles (2015)
antirez.com
antirez.com
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
Step 2: be a dick about it.
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.
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.
Nothings worse than digging through a ton of diffs to find the breaking change.
1. really short summary in a few words, ideally mentioning the relevant issue(s) in the bug tracker 2. Blank line 3. Longer message, if necessary, to explain the change
If I'm going to be looking back through commit messages, that's the type of commit message I want to read. I want to know whether this commit is interesting or if I can safely skip it.
It doesn't need to be complicated. Just write a short note as if you wanted to remind yourself where you left off when you come back from vacation.
when we figured out how to avoid a certain type error in typescript, we made sure to describe it in a way that we would find it again, or it would come up in a search.
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 descriptive.
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).
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.
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.
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.
I don't even think there is a choice that is "optimal in absolute terms" as you claim. However, consistency within a project is absolutely key and is something we can hopefully all agree on.
It's not "commits as subjects", it's commits as titles. And it doesn't come from viewing the commits through email clients. It comes from needing to know what the commit contains and why was the change done. That is, from having a descriptive title for the change. This is needed whether one checks the commit in their email, on Emacs, on GitHub, or cli.
>As an individual, I might use git to version a blog post I'm writing, and in this case I could use my own entirely individualized semantics for commit messages.
Sure, that's a niche use though, not the use discussed here, which is about commit messages for programming.
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]
Add user login link on home screen
Refactor authentication into separate classes
Lint PR titles conform to standard formatYou are truly doing god’s work :). I’ve led a similar initiative and same outcome, some love, but those who don’t, really hate it.
Link to login from home screen Enforce standard for PR titles
For refactoring, applying linting changes, or general formatting, I do prefer a prefix to indicate that it is not intended to change behavior. Something that is consistent for a project is good such as "Refactor:" or "Reformat:" or "Lint:" as a prefix to make it easy to spot these in the history is good.
I often see message such as:
Implemented new framework to... Edited 3 files...
Then someone will edit it to be imperative and it reads:
Implement new framework to... Edit 3 files...
Which is not really any better. They were past tense indicative because they described the actions of the programmer which are in the past. Writing from the imperative is not just better because it is more concise in english (shorter verbs) but because it is the natural way to describe what will happen in the program when the commit is merged.
Just the first line, right?
user/login: Add link on home screen
auth: Refactor into separate classes> 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.
Summarizing a diff frequently doesn't add information that the diff itself already includes. Title or no title.
I'm surprised we don't think about how to shout into the future more effectively. It might be ourselves that we're helping the most.
At work I follow whatever convention the team I'm on agrees with.
For my projects I use commit messages as a way to "tag" changes, more than to explain the changes using prose. That way it's very easy for me to search for changes in the codebase.
eg. #event-loop #fix #multiple-dispatch #repeated-message (remove the # and you get the idea)
#1234 fixed the fucking fooinater that wouldn't frobulate.
Are you always going to be on Jira? On Github? When people fork your project are they expected to clone your issues as well? When you migrate to another system are all your issue references still going to line up correctly? Did you even think to check?
Please continue to include the ticket reference. But also put some context in your commit message because that's what it's there for.
This is the same reason that even if you use a fancy documentation site, it should be generated from files in the repo.
"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."
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.
Also, commit messages are sometimes the "documentation of last resort".
In my organization, putting comments in the code is frowned upon. "Comments are lies! The documentation is in the tests!"
But the tests don't lend themselves to _reasons_ behind why the code was written a certain way, why a given approach was taken (for example, we needed to re-write a Rails database migration in a somewhat contorted manner to avoid a deadlock that was occurring in production).
In such organizations, the git commit message are often the best place to warn future programmers of pitfalls: "don't even think of parallelizing these table updates—you'll get deadlocks!"
[edited for brevity]
> Foobar packs JSON into binary
vs
> Our Rest API was slow and bandwidth heavy, so we wrote a library (Foobar) that packs JSON into a binary format. Now our messages are 50% smaller and 30% faster.
Git commit messages are worse offenders but there's plenty of criminals about!
Maybe it's time to dust off the "go to hell hat" and start demanding more info from the submitter...
JIRA ain't perfect though. The constant UX changes drive me nuts. At least HN still works the same way as 10 years ago, but JIRA keeps changing like a shapeshifter.