How to write a Git commit message (2014)

100 times this. I’ve worked at a company with a commit history going back to 1979 (literal paper logs at that point, plus in-file headers), and another company where we lost ~2 years worth of historical context/info to WIP commits because “our internal GitHub instance has that info” turned out to not be true when we migrated to a new instance. Nowadays, the relevant info from our PRs gets copied to git, and I hope in 40 years if someone has a question they can still see that history if needed.

I built a full pipeline around this. Basically allowed for a paved road for devs to automatically semantically version and deploy application and module artifacts for npm with semantic release by spinning up a repo with some boilerplate generators I made available to the team.

Since then I've been obsessed with the conventional commit format everywhere for my own projects. Even if the commits aren't parsed for versioning, it just gets you into the habit of thinking about the scope of the commits.

The laughable part about building that full paved road pipeline is that the biggest friction point was always when devs didn't use semantic commits. At the time when I implemented it I didn't have checks for the commit format at the pr phase. I DID have a commitizen cli option as well but that was "Too much friction". Oh boy did I get bit. As someone who was working on DX I was constantly surprised by how many questions I got about something as seemingly simple as the conventional commit format from a crowd of enginerds.

I've been using github-changelog-generator [1] for (you guessed it) automatic changelog generation, which adds bug fixes/features to the changelog based on issues and PRs, but sematic-release looks like it might be even more useful.

[1] https://github.com/github-changelog-generator/github-changel...

Conversely I hate these with abundance. If you feel that working on your project is a chore, why are you still working on it?

I prefer issue/card numbers as it makes it easier to visually group and search for common commits of a single task in shortlog. feat/fix/chore have no functional use in shortlog (for me!) and the mixed length moves the start of the actual comment and makes shortlog messy. That information can just as easily be put into the commit message. 2c.

This is probably more appropriate for private projects rather than public contributed projects perhaps where the benefit of conventional style is to be able to easily create changelogs of large number of commits.

Interesting, after years of software-development I arrived at almost the same pattern:

* [feature] -> a new feature, can be incomplete, but should be a contained unit of work that's usable to the enduser in some way.

* [code] -> everything that improves the code, could be refactoring, library-updates or preparations for a feature

* [bugfix] -> minimal commit only for fixing a bug, should (almost) always include a test to reproduce the bug.

Sometimes I also use:

* [build] -> for build-improvements

* [performance] -> for performance-improvements

I don't really have a problem with bullet points, conveying relevant information is after all the most important thing the message should do, but if that example is an actual one then it would raise some flags during review. Mainly because it's not super readable (mix of styles, super terse requires extra interpreting) but also because it mostly explains what has changed (most often unneeded information, as that should be clear from the diff) and not really why it is done that way (ok, the code might have comments, but still I expect the message to explain that). In my experience, using bullet points like this is correlated with this style of messages which just list 'I did x, y, and z' whereas a more narrative style, which can still go in bullet points, is correlated with easily digestable messages explaining properly the reasons for changes. Anecdotal of course.

> Headline + Bullet Points are far quicker to convey useful information

Not sure why the quicker qualification, here. Your example follows the article's guidelines exactly. (Except, as a minor point, the initial character is upper-case).

In fact, if each of the bullets were its own commit, this would be the default message of the squash-commit to master.

Just thinking out loud, but wouldn't this be best handled with separate commits for each of these atomic changes, with a merge commit describing the intent ins narrative form?

Don't ask me if I practice what I pushed there

Bullet points are fine, but again the message should contain the context of the change and the "why" of it, not the what and how (that's what the diff shows).

Writing a good commit message within those constraints is kind of like writing a haiku. It's kind of entertaining sometimes, though I think it should be a suggestion rather than a rule.

I know the articles calls it a rule, but really it's more a guideline. It's so that `git log --oneline` and `git shortlog` produce succinct output. It's also the email subject when using `git format-patch`. With all of these, the idea is to have a quick-to-read summary of the commit. That's all, really.

Indeed, I follow these rules but I routinely violate the 50 character limit. It's far more important for subject lines to be useful than to be maximally succinct; I'm not out here trying to write an essay in the subject line, but I do need it to be appropriately descriptive.

It's often difficult to find a summary in 50 characters, and it should be! Anything that's longer than 50 characters is probably too verbose too be viewed as a log.

I think Linus himself recommended at some point that 50 character subject restriction (in a time when 80 character wide code lines were also still a recommendation).

That wouldn't be important in itself, but Github trims your message at 50 characters as well. Because of that "feature" alone it's annoying to pass that limit.

I try to subscribe to the idea that if you cannot adequately describe your commit in a small number of characters (~50 is plenty I feel), your commit is likely too complicated. One size does not fit all, and if a workflow ain't broken there's usually no need to fix it. However most workflows are imperfect, there is almost always room for improvement.

But in the general case I find that if commits are not themselves concise and simple changes, they often should be broken up so that the moving pieces can be better tracked when looking back at the history.

I like this. Any advice other than "putting in effort for more than 2 seconds" has a lot of hidden assumptions about the context and organization around your code. Some days I only do a commit once at the end of the day as a backup. Other days I have 10 commits in 1 hour because everytime I thought I was finished I found something else that needed to addressed.

In practice, there often is not a very strict process around commits, so specific advice is often not very useful either.

Define 'specific change'.

A change driven by a business decision? Don't see how it won't work.

A change specific to a component? Try conventional commits with scopes.

Code change? You shouldn't use commit messages. Use e.g. `-G`, `-S`, `-L`, etc. instead.

By the way if you are not using fzf already, you should.

If you really want just one commit on your PR you can reset your branch to its target before you merge:

git reset --soft <target>

Which will undo all commits and leave all modified files in the staging area. Then you can make one commit and force push it to replace your branch @ remote.

This works well enough if (and only if) your company has a culture of small, atomic PRs.

But the PRs aren't part of your git repository? IMO a git repository should be self contained and not require a hosted provide to give context. It lets you manage your work with superior local tooling and without a browser running. Basically I take the exact opposite approach where my PRs are always just a short summary of the commit messages and provides a place for me to put the github specific things like the "Fixes #..". But I make sure my commits are a clean artifact of the changeset by themselves (ie. I do any squashing, etc, on them outside of the PR).

That's such a different approach than I've grown used to, but different platforms encourage different flows.

I've been using bitbucket (not the shiny nice new bitbucket) at work for years and its PR search is so abysmally bad that anything in the PR message but not in the commit message may as well not exist once its merged. `git log` is forever, bitbucket search is /dev/null

I'm curious what other affordances or lack of affordances encourage what git behavior.

For the code review step, sure, commit messages don't really matter unless your team reviews PRs commit-by-commit.

How many times do you actually change the default squashed message? If you write a series of garbage commit messages, I don't particularly trust that you'll write a very good squashed message, either. How many times do people skip updating the PR description with new information or features from comments? If your commit messages are good, the auto-squash message will be good and one will have a network dependency on GitHub to figure out what decisions went into that change.

In general I agree with your goal of a great commit log: 1 PR = 1 commit in the main branch. But I feel like GitHub is just the wrong tool to use if you want that. I used to use Gerrit, where commit messages _are_ your PR description. Sure, it makes you interact with git in some unfortunate ways, but the tradeoff is enforced commit cleanliness.

this works until you want to leave Github for whatever reason

There's a few reasons why this is a lossy workflow compared to commits with proper messages that are later merged, not squashed into one.

1. The PR itself becomes a single giant commit. To adequately explain the diff in a single message would require writing an essay instead of a few paragraphs. It is also now hard to tell which part of the PR message is associated with which part of the massive diff.

2. If something breaks, you can't dissect into which part of the diff caused the problem.

3. It's harder to document your work as you go. I may be working on a PR for days or weeks. Commits give me an opportunity to document each part of my change _at the time I make the change_. It's a chance for me to record how and why at the time it's fresh in my head. If I wait to do this until the PR is ready, I likely will have forgotten some bit of context I wanted to record about the commit.

4. It encourages sloppy commits, making a large PR harder to review. Ideally, I should be able to review a large PR by looking through each commit.

If your reply to all this is to say you should just submit smaller and more frequent PRs, fine, but then why ever have PRs that consist of more than one commit?

> I prefer Github's method of "git commit messages don't matter, pull requests do".

This is a bad idea unless it works well for your specific company workflows and you don't care about the future possibility of changing platforms.

Git repos are designed to be self contained, decentralised, and offline-first. If you only care about how things look on github, then the repo will have poor usability outside of github - ie. on your workstation, in your local git tools, on a repo mirror, etc.

Git commits can be a powerful tool for understanding code if the messages are useful. They are immediately accessible through local tools and can quickly add context to a block of code without breaking immersion. But that immersion is broken as soon as you hit a commit messages like "Merge pull request #123" or "fix bugs".

This would be a lot more reasonable if GitHub would provide tools to review the ultimate commit message in the same manner as the commit content.

> 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch

Please don't do this. It erases history that's really useful for tracking down the cause of bugs.

There's plenty of ways to use git log to filter commits if a pretty history is your goal.

I agree with this. Oftentimes I am experimenting around (obviously on a separate branch) and use commits as checkpoints. Not every commit is a perfectly polished state. Using separate branches and then squashing when it is ready, gives me the freedom to experiment without constraint, and then clean things up when it is ready

I abhor “Squash and Merge”, because I do take time to make good commits. They each pass tests, they have messages, and I rebase fixup commits away. For me, a merge commit is semantically meaningful (it even gives me a place to put who reviewed it in the merge commit message).

This probably seems like a whole lot of work for no benefit. However, I can’t tell you he number of times I’ve been on crappy plane wifi, hit `git blame` on some line and been able to comprehend my state of mind making a change years in the past.

Git history is a form of communication.

> I prefer Github's method of "git commit messages don't matter, pull requests do".

By doing that, you lock yourself into relying on Github in order to get the context behind a change rather than looking at the commit messages for a particular branch. That means, you cannot easily get that information just using git on the command line. On the other hand, if you put the context in a series of well formatted commit messages, you can get that context by reading through the commit log, either on the command line, or in Github by clicking on each commit.

> 1. Make it so the only merge strategy allowed on a repo is "Squash and Merge", so each PR = 1 commit in main branch

This leads to very large commits which cannot easily be reverted once any other commits that update the same files are added to the base branch. Also, in this case, the merge commits are essentially redundant, so why have them? There's nothing that prevents one from amending their commit to reference the PR number and eliminate the merge commit entirely.

> It's easier to be more expressive in a pull request, and intermediate changes while working on a PR aren't super interesting to me.

It really comes down to how those changes are presented. For example, if the change is one commit that adds a new method, and a second commit that adds calls to that method, that makes the change easier to review. Also, if a bug is found in the method, you can make a revert commit to remove all the calls to the new method, another commit to demonstrate the bug with one or more tests, another commit to fix the bug and update the tests to reflect that the fix works as expected.

If the commit was just a single PR commit, and another PR was merged, then one would have to craft a commit to undo the changes pertaining to that bug and then make a new commit in another PR to add the updated implementation. This makes it harder to see what the fix was since you essentially remove the entire feature and then commit a new version of that feature.

The individual commits aren’t interesting until you need them. They should be organized such that they remove the desire to squash them together.

Having a well written commit history is in the spirit of the tool and is the more professional approach.

It may be heretical but I tend to agree with this. Also at my workplace we tend to be standardized around PRs doing squash merges so there’s not really much point in having detailed interim commit messages anyway. As long as the PR has good information (and of course is linked to useful work items with good information) that’s usually good enough for me.

(Of course more often than not people have empty/useless linked work items, and PRs with useless titles and descriptions but that’s a whole different kind of problem.)

Write a commit script that pulls in the PR text into the merge commit.

I totally agree with this, I'm not a fan of the written-in-stone nature of commit messages. Just like code, it's nice if log history is editable too in case your forgot something, or if you want the message to mention future changes that back reference it.

I'm with you!

The PR commit can have sooo much good information, that can be used by so many teams. Loom videos for a quick demo of the feature. A concise description of the impact on customers, support teams. Deployment and feature rollout considerations.

I do try to make the individual commits somewhat presentable within the PR... a few extra minutes polishing the subjects lines. But nowhere near what this article, which seems to be suited for non-PR workflows such as mailing lists+patches, or workflows where every PR is squashed?

There's even a pitfall in putting too much "why" in the commit messages -- some programmers will be tempted to keep it out of the code, ie never comment their code.

I'm an agnostic who keeps my distance from self-proclaimed heretics inhabiting the modern-day Church of Github (which formed as an offshoot of the Cult of Git, which itself emerged after launching a savage religious war with the iconoclastic Sect of Subversion), who prefers to have both a logical, reviewable commit history AND informational pull requests.

Smashing commit history via squash makes debugging harder. Provided you have the interactive rebase chops to pull off crafting a decent granular history, you'll reap significant dividends down the road if you keep that history intact. Because it's right there for you to use with `git blame`, etc.

And then why not have proper discussions in the pull request with reviewers? Sometimes important stuff comes up in review. Sometimes you might close the PR and start anew. Sometimes the PR gets incredibly lengthy. Maybe the result is a commit history which condenses some abominably lengthy PR.

There's no need to choose between them. You can have both!

I used to do that as well. The problem here is that PR belongs to a particular service provider (GitHub, GitLab and whatnot), and thus can be easily lost if you move providers. Or even if you simply move commits to a new repository (for instance you need to clean out some sensitive information from git history). In that sense having as much context in commit messages themselves saves the day.

I subscribe to this and:

> "The Not Rocket Science Rule Of Software Engineering: automatically maintain a repository of code that always passes all the tests"

https://graydon2.dreamwidth.org/1597.html

Intermediate commits to produce a pretty history while not passing the tests reduce their usefulness to about zero.

Yup, we do the same and it works out pretty well this way.

This really treads on the char limit in the titles though

We do the same and it works pretty well. The problem with that approach, though, the codebase may live for decades but issue trackers change and old tickets usually don't get migrated to the new system.

Curious, I've run into this approach in the past and learned to hate it with passion.

That place used JIRA where the typical ticket ID was around 10 characters. That wasted a lot of prime real estate, e.g. in my email inbox, in history views (tig, gitk, and so on).

I also don't see the claimed benefit for git blame. In a real code base with significant history, it happens often enough that the first blame is an unrelated refactoring and you need to dig deeper. Therefore, I find that best practice is to look at the blamed commit first instead of the ticket. That gives you the full commit message, which can still contain a reference to an issue.

Putting footer lines like "Fixes: <issue>" into commit messages works much better. It's just as easily visible in git log etc. and doesn't waste space.

None of this is really worth obsessing over I think, but one point in favor of imperative is it tends to also be the tersest phrasing, which is convenient if you're also aiming for 50 characters max.

So long as the meaning is clear, it really doesn't matter IMO. Just write it so that when viewed in isolation the meaning of the message is clear and matches the changes held within the commit.

Anyone who gets up in arms over "fixed" vs "fix" needs to get a life.

I use imperative, but for other projects which don't I switch to indicative if that is the style. Personally like imperative more, not sure why, just preference.

> Is it really that big of a deal to use the indicative sometimes and imperative other times?

'big', don't know, but wouldn't be surprised if there's an objectively provable higher cognitive load for having to read a mix of both (or, god forbid, other styles thrown in there as well) vs one consistent style. Just like there is for code etc. And some people are affected by striving for consistency more than others, so for them lack of consisteny might cause some extra friction.

The imperative mood/future tense ("this commit will...") makes the commit the subject of the message, the past tense makes the developer the subject of the message. In my (limited, personal) experience, the people who insist on past tense commit messages have more trouble killing their darlings, are more likely to take review comments personal, and are more likely to view (part of) the codebase as theirs rather than the team's.

So for me, it's not about the commit message itself, but the communication style says something about the developer and how I best approach them.

My take on this requirement is that it helps developers let go of their attachment to the code they've written.

> Why would anyone outside of the realm of die-hard FOSS on Unix-like systems wrap text to 72 columns?

Because if the commit is performance related, including regression test results may be mandatory. Test results will be in some fixed format e.g. tabular, commonly exceed 72 columns, and become gibberish if wrapped.

My vim will automatically wrap when I am typing a git commit message.

Should be set by default from here: https://github.com/vim/vim/blob/2f0936cb9a2eb026acac03e6a8fd...

vi :set tw=70

There's a good chance this was made in Github's squash+merge dialog.

Edit: never mind, it's auto wrapped at some number

Emacs + magit and auto-fill-mode

Command line? git normally opens your chosen editor and you are free to write away to your heart's content.

I guess you could stuff multiple -m in there and git will format it nicely, but the editor is for writing and is best used for that.

> It just seems like a lot to type in the command line.

I spend my entire workday day in Vim.

If you don’t supply `-m`, `git` will pop open your `$EDITOR` with the new commit message. You can use whatever tools you like to wrangle text in there. I use vim, so it’s just a quick `gq<motion>` to format everything.

I write it as normal prose and then pipe through `fold -w 76 -s` to line break. TextMate makes this easy with its "Filter Through Command" menu item.

It matters to the same degree as being consistent about variable naming. It doesn’t change whether the system works, but if everyone is consistent then it’s easier to read and understand later.

Have you gone through a ticketing system change yet with a developer team? I've seen several, and not once was "we must import the old PR's/issues/features into the new system" given any serious consideration. Conversely, every source control system migration I've seen took great pains to preserve the committer, the date and the full commit message of each separate commit.

Point being, in a few years all your [external references] will be useless. Can your commit messages explain the commit context on their own?

But why? That's even more useless than just describing a commit in a couple words.

I'd rather see a commit saying "fix bug" when bisecting or reading a commit history than ":heart:"

I've tried with the idea of an autocommit chron job or something which just uses timestamps and periodically rebases things to avoid tons of commits.

Honest question, do you really expect your history to be meaningful long-term? Or are you simply taking the approach that the commit message is meaningless and a developer instead use GitHub search to find a PR relevant to a change they're investigating.

For example, I pulled up one of your projects and the history (https://github.com/transitive-bullshit/kwote/commits/main) is less than meaningless, compared to i.e. using emojis as a shorthand (https://github.com/tiangolo/fastapi/commits/master)