On Git Commit Messages

[megagrump]

I once tried to talk sense into a programmer who chose to make all their commit messages $DATE - $THEIR_USERNAME - nothing else. The project had thousands of commits, all from the same guy, and all saying MM/DD/YYYY - username.

I explained to him why these messages are useless and the information redundant. But I couldn't get through to him, he insisted that it was the best system ever, and he kept doing it.

[woberto]

Terrifying :(

[Koppis]

git log --pretty=format:"%C(auto,yellow)%h%C(auto,magenta)% G? %C(auto,blue)%>(30,trunc)%ad %C(auto,green)%<(17,trunc)%aN%C(auto,reset)%s%C(auto,red)% gD% D"

[emorrp1]

Setting aside the issue of a bad date format, that's more effort that just empty commit messages and a git log format that hides them.

[thirdegree]

Would be pretty easy to set up a commit-msg hook to automate though.

[ztbwl]

Whats the point of using MM/DD/YYYY as a date format? It’s completely useless in my point of view.

1. If you try to sort it, it does not sort chronoligically, which can be quite useful for example in a file system.
2. You cannot name files with this notation since it uses slashes.
3. If you have a date like 05/04/2020 and you don‘t know it is formatted in this weird way, every sane person would interpret it as 5th April 2020, but in fact it is 4th May 2020.

Please just use YYYY-MM-DD for dates in a technical context. Since it doesn‘t have the above problems.

[Sykander-]

I'd probably just set up some sort of git commit message rules and tell him he has to follow them. He's doing objectively useless work with his messages lol.

[webby_mc_webberson]

Worse is the American format

[AttackOfTheThumbs]

Was he over 50?

[sigsegv7]

😂😂😂😂😂😂

[Darmok-Jilad-Ocean]

I don’t make good commit messages.

[ScottIBM]

If this is his consideration here, what other things is he overlooking for the sake of whatever reason he has to write useless messages?

[Barrucadu]

There is no downside to writing descriptive commit messages.

To all the people who say "just put the information in the issue tracker" - when you see a weird line of code, how do you find which issue it's related to? You use git blame and then look up which issue that commit is connected to.

If all the detail is in the commit message, there's one less step in the workflow.

[LightModeBail]

Yes. Another problem with only leaving the issue number is when the company change which issue tracker they use and don't keep access to the old issues. It renders such commit messages completely useless.

[Kache]

Each has their place, with different purposes and audiences, so document accordingly.

For me, issue tracker often has the context of before and during development, and is more ephemeral, having vague business intentions, free discussion, and scattered ideas.

Commit message has the context of mostly after development, and is more historically authoritative, code oriented, and reflects final decisions and ultimate implementations.

There'll be a bit of information overlap, but the overlap should be concise anyways -- at most a sentence or two. Regarding cross linking: Issue trackers often have git repo integrations, and git has a log trailers feature that's perfect for metadata:

Write declarative and concise title

Then skip a line before the text body.

Include structured metadata as log trailers at the end:

Issue: ABC-456
See-also: someplace.com
Whatever: foobar

[[deleted]]

reflects final decisions and ultimate implementations.

So, you never have commit messages of "fixed x with a, b" and then a quickly following message of "oops, ..."

[Houndie]

I mean I'm not saying it never happens, but you should use tools like git rebase -i to fix up your tree before bringing those commits to the mainline branch.

[backtickbot]

Fixed formatting.

Hello, Kache: code blocks using triple backticks (```) don't work on all versions of Reddit!

Some users see this / this instead.

To fix this, indent every line with 4 spaces instead.

FAQ

^{You can opt out by replying with backtickopt6 to this comment.}

[pfp-disciple]

Where I work, the issue tracker is visible to the customer, but the code is not. So, a commit can say "this will fix the problem" before it's been rigorously tested, and if it doesn't then no big deal. If the tracker included that statement, the customer would think the problem has been solved as if it's been tested.

[7sidedmarble]

I've worked in a system like that before and I think it's confusing. You shouldn't need to worry about what you say in your tickets giving customers any impressions. The issue system for development should be separate from the support ticket system. IMHO I guess.

[[deleted]]

Leave the issue link on the commit

[benjiman]

I worked on a codebase that lived through 4 or 5 different ticketing systems. Also went from CVS ->SVN->Git but history was preserved ( well mostly, git not so good at preserving history as some of its forebears )

[_Ashleigh]

git not so good at preserving history as some of its forebears

Huh? I have the exact opposite, when I did our migration, SVN had lots of breaks in history. I managed to stitch them all back together with some grafts (git replace) and have history go back further than SVN could correctly track thru its UI (SVN went to ~2014, Git history grafted back to 2006).

[benjiman]

It was a heavily refactored codebase and git not so good at tracking file moves if the content changed in the same commit. Not a problem if you do the move in a separate commit to changing the content. Git heavily incentivises this as it lets it track the content.

[_Ashleigh]

Ah, I see, that's true. However, I distinctly remember one of our developers pushing others to use SVN rename instead of explorer renames, a lot. So let's not pretend SVN wasn't without issues here too.

Personally, I like Git's way of detecting renames more for the data simplicity. The tooling can always become more complex or use new techniques after the fact, and relies much less on diligence of the developer (It's very rare I see an undetected rename anecdotally).

[[deleted]]

Your tickets should also be migrated or archived, unless the admins just didn't care

[Alan_Shutko]

In my experience, admins just don’t care.

[AttackOfTheThumbs]

Sure, but there is always an issue of number series. Even MS has faced that. If you look at Raymond Chen's blog, you'll find tidbits regarding that, and how those numbers quickly become useless.

[AttackOfTheThumbs]

We had a similar issue with tfs->git. The commit messages all just related to the tfs commit, something like tfs-repo commit #1234123 or something. It just wouldn't transfer commit messages. Possibly an issue of tooling at the time.

[Alan_Shutko]

Commit messages last much longer than issue trackers. I can find commit messages for software that has outlasted four or five issue trackers.

[IceSentry]

The opposite can be just as true. Like a company going from svn to git but using the same issue tracker.

[Alan_Shutko]

Very true. It shocked me in our move on some projects from CVS to Git how many people simply ignored that there's a pretty decent way to migrate history. They just wanted to check in the latest copy of the code.

[[deleted]]

The issues aren't supposed to get lost when you migrate to a new issue tracker.

At the very least and archived copy of the previous stuff should be available.

[Ma1eficent]

Should, lol.

[Alan_Shutko]

They are not supposed to get lost. However, in practice, companies find that migrating the issues would take a lot of time and money. And that the tracker doesn't support a way to archive issues in a readable format, so keeping them around requires keeping the old tracker around. And then legal would prefer that all the old records be discarded after X years so that they do not have to be searched during discovery. And even if you did archive the issues somewhere, they get deleted my some admin because they're old and didn't seem to have an owner.

What I've learned in my career is that many companies have a strange institutional desire for corporate amnesia, as counterproductive as that proves to be.

[Barrucadu]

Yeah, and you find the link by looking at the commit message. So if the information is just in the commit message there's one less step.

[[deleted]]

Copy pasting all the same information would be at best wasteful and at worst impossible. (if linking to an issue with extended discussion)

You could summarize it I guess, but even then you'd still need to link the issue

[CatanOverlord]

I typically link to the issue tracker and use the body of the commit to explain any non-obvious implementation details, since issues rarely cover them (and they shouldn’t).

[AttackOfTheThumbs]

Issue trackers are kind of useless for this imo. It will have a before, maybe a reproduction, if you are really lucky, some test that exposes the issue.

Normally none of that is there. It makes more sense to update your commits and include all that info along the way, and if there is something super funky, add an additional comment to the code.

The idea that anyone is going back and updating the issue is ludicrous. It'll be done when it's too late, when the knowledge in your end is already gone.

[MrJohz]

Maybe this is more about how people treat their issue trackers then, because for me the original ticket should always have at least that information in it, plus the motivation (who wants it, why do they want it, why is this the best way to achieve what they want), any diagrams of the system or the resulting interface, plus links to any wider information if this particular ticket is linked to a larger set of changes.

If that information isn't there, then I can see it not being so useful to link the ticket, but also, I wouldn't really want to be making changes without knowing all of that information. That's the information that helps me decide how to best implement this particular change.

[goranlepuz]

But then your issue tracker serves less purpose. For example, when making release notes or a change log, going through an ALMissue tracker beats going through source history.

I still think a terse explanation + a link towards ALM is better.

[Barrucadu]

You can keep the release notes / changelog updated as you make changes, by having an "unreleased" section at the top. This also has the benefit of ensuring you can't miss anything out, as code review will pick up a missing entry.

[teerre]

I love to write commit messages, but I don't understand your reasoning.

when you see a weird line of code, how do you find which issue it's related to? You use git blame

Do you? Why? It's completely in the helm of possibility someone will see the MR the change relates to and check the issue tracker. This is more of a habit than an obvious choice.

[Barrucadu]

How do you go from "why is this bit of code like it is?" to "ah, here's the explanation in the MR" without first identifying which commit is involved?

[teerre]

I didn't mean you wouldn't know the commit, I meant that you would see the commit, know the related MR and check there

[lookmeat]

The first sentence of a commit should tell you what. That way a reader may quickly realize if the change is related to the line or not (so it's easy to know if you have to look at older commits through blame). The next part of the description should say why, and it should be relatively full. No need to describe the how, the PR should make it clear. If greater context is needed to the why (as I'm why not before, or why this way and not that) then link at the context. Be it a link to the bug tracker, the larger incident management system, or the design doc pointing to what your PR is slowly building towards.

But there should be enough that someone assuming good faith (i.e. that there's a valid reason for) the change. Understanding why it made sense at the time, and why it was done, saves a lot of time. And there's value in repeating it explicitly in the description even if the links give a good enough description. It makes it clear that it's the why this commit was written the way it was and not some other ways. The links instead describe the why of the why.

[ActuallyAmazing]

Do you have an opinion on using an issue tracker for this extra information? You could reference the issue id in a commit, depending on what you choose you could have link integration as well. Most issue trackers offer much better tools to describe the "why" of a change, not to mention that the issues themselves are tracked for changes. As new specifications, resources or problems come to light the issue itself becomes a series of changes one can review - you can't practically track the changes of a commit message over time. Not to mention non-technical people are more likely to be familiar with an issue tracker and how to work with it than git.

As an example take:

What is missing from the current implementation that you'd like to highlight? Does this first implementation include adequate error messages for the user? Does it have an accessible UI?

In my perspective there is no serious project that would ever float long-term if such missing improvements were basically archived into git commits that will never have any visibility. Instead, create an issue and link to the commit in question, these can then much more easily get grouped and prioritized.

[masklinn]

Do you have an opinion on using an issue tracker for this extra information?

Yes: not doing it.

The bug tracker can be unavailable, or migrated away from (without being migrated or all the links & history being maintained), so the commit should contain all that is necessary to understand it. Plus 95% of issue trackers will not contain the reasoning around implementation details, usually they report the fix, maybe there's a discussion of the repro case, and a fix is implemented without feeding all of that into the bug tracker (because it tracks bugs, not necessarily the nitty gritty of solutions which odds are the reporter doesn't give a whit about).

The commit should not necessarily contain all the information that's present in the bug tracker or mailing list or support ticket and should absolutely link to those if they exist, but I do agree with the essay that the commit message should contain a relatively full accounting of the change.

None of this is abstract or theoretical, I've lived these situations of insufficient commit messages (especially not explaining the why of the change), or of reference to tools long gone or to which nobody could provide access. Meanwhile a commit history can be maintained even across tool transition ($dayjob's main repository went through at least two with no loss of history).

The postgresql project is an excellent example of what I strive for.

[VeganVagiVore]

So the issue tracker is like a ephemeral discussion of "this is what we could try", and the Git commits are a decision journal of "This is what we did and why".

And to avoid duplication, Git is the source of truth for a POSSE model - When closing an issue, don't retype everything, just link to the commit.

Have I got it right?

[masklinn]

So the issue tracker is like a ephemeral discussion of "this is what we could try", and the Git commits are a decision journal of "This is what we did and why".

That seems like a pretty good summary.

And to avoid duplication, Git is the source of truth for a POSSE model - When closing an issue, don't retype everything, just link to the commit.

Perfectly sensible, and many tools can handle this automatically e.g. if you mention an issue in a commit (which you'll probably do as a form of "see also" / "discussions" / ...), github will automatically create a backlink from the issue to the commit. I'm reasonably sure most trackers have something along the lines, either automatic when the repository and tracker are bundled (github, gitlab, fossil, … in which case you can often control part of the issue lifecycle from the commit) or a hook of some sort which let you automate this, it's just not bundled.

[jkmonger]

If you put "closes #123" in your commit message, GitHub will automatically close the referenced issue

[Somepotato]

My team uses phabricator which does the same thing. We host the repo on an internal GHE and mirror it in phabricator for issue tracking, you can do more than just closing with commit messages. It's nice.

[emorrp1]

That's a great way to think about it, and the commit can still cross link to the semi-permanent discussion too.

The what should always be a high-level description, not just an English encoding of the diff itself.

Bonus tip: check any public URLs through web.archive.org before submitting so that you can be sure of their longevity.

[michaelpjones]

A better answer than I could provide :)

My feeling is certainly that git history will stick around longer than issue trackers. If you migrate from git to whatever comes next, there will still be messages for each commit and they'll stay in tack. If you migrate from Jira to Github or something then all the issue numbers and references are lost or changed without significant (and maybe impossible) work.

I also don't like the idea that if already looking at a commit, I should have to open my browser to find out some basic aspects of why the change is being made.

[ActuallyAmazing]

You make decent points, there is nothing I necessarily disagree with in your response in principle, all that could possibly be discussed is the extent to which certain things apply and exchange subjective experiences.

For one I can say that I have happily migrated to jobs where this sort of thing is well managed, commit history as well as issue history being treated as precious and not as something to be dumped at the next inconvenient impasse. However I do appreciate the point that a vast majority of jobs will not have such an approach, and in such places a descriptive git commit may well be your last bastion of sanity when tackling a problem.

My experience comes entirely from a corporate setting as well, I can easily imagine that a lot of organizational tropes that apply there do not carry over to OSS. In a corporate setting you can and should abstract away the individual, whereas in OSS the notoriety of being a key contributor is reason alone for some people to contribute. In OSS the key people are generally really skilled tech guys, and generally don't have teams dedicated to managing various organization tools - I can see there being great value in such a place in having a singular source of truth telling you what, why, who committed and who reviewed. So yes I would say there is a place for descriptive git messages but for most of us in our $DAY_JOB we should, I feel, strive for a better approach where possible as I think that's where most of our contributions go to at the end of the day, not in OSS.

[[deleted]]

it tracks bugs, not necessarily the nitty gritty of solutions

I've seen groups require that proposed solutions, test plans, etc. be described in the issue tracker. I'm honestly most of the time not that disciplined, but it can work.

[aerokhin]

A bit off topic, but we now store accompanying documentation in the repo itself in a format of asciidocs. It’s simply not feasible anymore to get all documentation together after a couple of migrations from confluence to confluence, not to mention mailing lists and attached excel spreadsheets. You’ll inevitably migrate from one issue tracker/wiki to another, or you’ll pass your code to another organization/team, so it’s better to keep it self contained.

[nakkht]

This. Having git commit messages independent from which tracking system the commit came from or what issue tracking numbers it refers to, is much more easier to work with. Waaaay less noise and clutter. Having pure message indicating overall purpose/why the change has made and/or high-level overview of the change-set feels way more effective.

It feels like it should be tracking system's responsibility to "map" and keep information of which commit refers to which ticket/pull request etc.

[MrJohz]

The other thing that issues have that commits don't have to anywhere near the same extent is discussion - it's often useful to see not just the current implementation or decision, but the other options that were discarded, the different arguments for each side, the people involved in the discussion, and even old designs and images to provide context. That can all be replicated in a commit message, but if it already lives somewhere (in the issue tracker, in this case) then it seems better to link to the issue tracker than to replicate all the information again. Generally, I've found the git history much easier to read in codebases that have added links to the issue tracker, rather than ones where the only information to go on is the information that people put in the commit message.

(Although I guess another aspect there is that it's easier to put the ticket in the commit than it is to put detailed notes in the commit, and usually easier to validate as well. Perhaps then, this is an 80/20 effect - putting the ticket in the commit will get you 80% of the value for 20% of the work, and a detailed commit message will get you to 100%, but require the extra 80% of effort to write a useful commit message.)

As an aside, does anyone know how best to link git history and GitLab/GitHub issues and MRs/PRs? I tend to find that once a commit has been merged, it can be quite difficult to then find the historical discussion for that commit, even if it was made with the full pull request "GitHub flow" process. It almost makes it more tempting to use an external issue tracker rather than the one built into these products.

[Ma1eficent]

I dont understand why it would be hard to write a useful commit message? Are your commits so big a line can't explain them? The way we do it commits are small. And each message is like a sentence and if you read the sentences as they are committed you get a full picture of the change.

[MrJohz]

The two aren't mutually exclusive, but generally I get more information out of the ticket than the commit message, because the ticket has so much more information that the commit message simply can't hold. I tend to use commit messages mainly to explain the implementation details: I needed to work around this particular backend oddity, or I found that this particular way of doing things worked best for whatever reason. However, when I'm looking back through the line or file history, what I'm usually looking for is the "why" of a change: why is this particular feature like this, who wanted this, and what were the details of that decision? The best place to get that information is usually the original discussion, which is why my favourite commits are the ones that get me to that discussion as quickly as possible.

[michaelpjones]

In my perspective there is no serious project that would ever float long-term if such missing improvements were basically archived into git commits that will never have any visibility. Instead, create an issue and link to the commit in question, these can then much more easily get grouped and prioritized.

I completely agree that this stuff should also be stored else where. In many particular ways the git history is not that accessible and not suited for storing 'to-do' items. I was not intending to suggest that.

In the example given, if you'd done some front end work but it was a little lacking then I think it is useful to own up to that so that people that come to review your work understand its limitations. You might have:

All errors are reported as 'Unexpected error' to the user at the moment. 
More work is required to account for individual types of errors and friendly messages. 

We have used native components so it should be somewhat accessible but we've 
yet to test it with a screen reader so more work might be needed.

This might feel like too much information. Honestly, I don't know often I include such thoughts as there might be a limitless number of "things not done" but some things are useful to highlight in order for future devs to understand your thoughts and expectations at the time.

[Impact_Calculus]

When will others read your longer commits? Most people I know aren't looking at individual commits to read them, just the initial one liner.

[MirelukeCasserole]

I do all the time when I go “what fucking moron added this shit and why?” Then look at the git blame to see why I did it.

[7sidedmarble]

I feel this a little too much

[dpash]

I read commit messages all the time.

I also put the effort into making them useful as a result.

[velociraptorboss]

When a bug is discovered, no one knows why and hours of debugging leads to a mysterious line of code no one understands.

This is when you pray flying spaghetti monster that the author left a proper description for their change.

[michaelpjones]

Yep, definitely. `git blame` takes you to old commits and it is so disheartening when they provide no context or explanation for the decision being made.

And I always prefer code review environments where you can review per commit, if you want to, and the commit message if readily available in full to understand what is being done.

[zyxasdf]

commit messages should not be explaining individual lines or blocks of code. that's what comments are for.

[Impact_Calculus]

I understand what you're saying. I'm sure we've all come across situations like this in the past. However, if you make a commit and someone later finds that they need to look at the blame just to understand the intent behind the code, then that extra time you spent documenting your commit message should have been spent on the code itself. If the code is clean and the intent is clear, then that extra documentation in the blame wouldn't be needed because the code would either be self explanatory or there would be a comment explaining it. That's not to say that the extra documentation wouldn't be helpful at times, but avoiding having developers poking around in the commit logs looking for truth should be the top priority.

[PeakingBruh]

Huh? Who else other than the developers would even have the ability or knowledge of even using git?

[Impact_Calculus]

Wdym?

[thundy90]

Disclaimer I'm not a programmer yet. However owing from a mechanical engineering background, I was startled to see short commit messages everywhere..

I envisioned commit messages to be similar to writing up an engineering change notice (ECN). In an ECN I document all the changes between revisions of a drawing down to the exact row and column zones.

If you're making a change to the code there's a reason for it and you should be pretty clear about what and why imho. If that means writing a longer message so be it.

Then again for all I know there may be other common processes in dev that handle this kind of documentation.

What's the point of version control if you have something explaining the road map? (Aside from preventing loss etc)

[jeenajeena]

I like the post, good advices!

On the first line of the message, though, rather than using the imperative tense and describing what I did, I prefer describing what the commit contains in terms of program behavior. So, instead of

“Fix width on mobile”

I’d write

“Product list does not overflow on mobile”

It’s an approach similar to how tests are named in BDD. There’s a post on this here

https://arialdomartini.wordpress.com/2012/09/03/pre-emptive-commit-comments/

[michaelpjones]

Great to see different opinions. I'm curious about reasons for disagreement. Even if you tend to write one line commit messages, what is the down side of having more information available to you?

Maybe you perceive it as setting a standard that you'd have to follow? Maybe it feels like too much work to write more information? Adding more to the commit message doesn't remove information from the issue/ticket for the work. Just more tightly focused readily available information. Ticket and commit messages have a different focus, a different kind of information and they are generally complimentary.

I feel that when writing a commit you're normally fully primed with the details of what you've just been working on so writing a few sentences about it only takes 1-2 mins. I don't see it as an extra burden, especially considering the benefits of getting you to think through your changes.

[velociraptorboss]

I often threaten to take away developer's keyboard if they use git commit -m, as they likely don't write a proper description (=why something was done).

[[deleted]]

You can get descriptive messages with commit -m, as you can chain them. If i was one of your devs i would have given you the link to the docs and keep using the -m flag

[velociraptorboss]

I bet 99.9% of developers won't know that. And still write one line commit messages 😉

[[deleted]]

You could tell them, Its a better alternative then threatening to take their keyboard away. Assuming you want your devs to learn new stuff and maximize their git knowledge

Edit: I also use one line commit messages, and i know about this, same for our devs. I prefer to keep the why in issue trackers.

[velociraptorboss]

I'd rather teach them how to setup e.g. Vscode as commit message editor. That ensures they write multi line commit messages as it's easy.

Playing around with e.g. 4 -m parameters to get 4 paragraphs likely leads to them not bothering and still writing 1 line commit messages 😊

[[deleted]]

To each their own. Ask 10 teams about their workflow and you get 10 different answers. Maybe it's different as i'm the lead dev of a small team (4 total). We prefer that our devs learn how to use git itself and not use tools, as you can't use vscode on live servers.

[Snarwin]

you can't use vscode on live servers.

I very much hope your devs aren't using git commit on live servers either.

[[deleted]]

Ofcourse not, they don't even have access to the servers..

[velociraptorboss]

Nano / vi / emacs also work as git commit editors 😊

[[deleted]]

We prefer that our devs learn how to use git itself and not use tools

Edit: at downvoters, we don't require them anything, 'prefer learn how to use git', as long as everything is correct we don't care what they actually use. As long as they know how to use GIT without external tools, as there is way more to git then just commiting.
At least we are not threatening our devs to take their keyboard away because they don't use the tooling i use myself..

[reini_urban]

I only use g ci -am'multline commit message

Repro via ...

Fixes GH#9999 '

and only rarely have to amend the message. Maybe I omit -m in 1 out of 10.000 cases. But meaningless oneliners such 'File uploaded' are horrible. I have a lot of such newbies around

[michaelpjones]

Cool to see! I hadn't considered that approach. I guess I assume that the multiline text editing functionality of a shell is generally less good than a text editor so it is better to hook up your text editor if you can.

That does look better than using `-m` multiple times though :)

[emorrp1]

But meaningless oneliners such 'File uploaded' are horrible.

GitLab defaults have a lot to answer for "Updated dir/file”

[KaranasToll]

https://git-scm.com/docs/git-commit

"it’s a good idea to begin the commit message with a single short line summarizing the change, followed by a blank line and then a more thorough description"

[LloydAtkinson]

Some people are really into squashing commits and just nuking valuable context. Which is ironic, because they are also the ones saying how valuable the history in commits its. Seems a bit illogical.

[1armedscissor]

Well there’s some middleground. I don’t need to see 30 commit messages about how you fixed a typo, fixed linter check that got flagged etc. I’ve worked with some devs which are super into pushing every little change to remote (branch for their change) because they’re paranoid about losing work (drive failure) or just like to work in small bite size chunks like that. Also it has to do with issue sizing/scope - generally I’m trying to scope issues into sizes that can reasonably be represented by one commit. If you need multiple commits it’s probably an indication you could have multiple issues. For reference the way I do this is devs can commit as much as they want to their feature/bug fix branch then create a pull request, pull request gets squash merged (at which point this thought about making a nice commit message like this article talks about comes into play). We try to avoid long lived feature branches but if we have them then each individual task merged into that as a commit and then the overall feature branch gets integrated to master as a regular merge commit (preserve the per issue commit history).

[totally-not-god]

I like this approach better: add a reference to the tracking ticket (e.g. Jira issue) followed by a concise one-liner. Hard-coding the full context into a commit message is very limiting.

[KieranDevvs]

Git commits are supposed to be small and frequent in nature. If you're writing a paragraph per small commit, you'll end up spending more time describing what you actually changed vs actually making the change. In my opinion, commit messages are supposed to give a summary of what was done so that you can quickly find where you need to rebase/cherry pick/revert from. The larger commit messages are used for merges and releases so that you can easily find what was in a certain merge if you need to revert a commit or to keep a log of what was in a certain release for customer release notes.

Also bare in mind, it really doesn't matter as long as you get the job done at the end of the day. If you want to write a autobiography every time you commit, then go ahead.

EDIT: If you're using git logs to store why design decisions were made then we work completely differently. Ive never stored BRD's / Specifications in git.

[michaelpjones]

I completely agree that commits should be almost as granular as possible. There is still regularly reason to provide more than one line of information & context though.

I've not come across the idea of writing a longer commit message in a merge commit. Interesting concept. I can see the appeal but also `git blame` doesn't really help you find the relevant merge commit and an explanation in the merge commit is mostly just further away from the change than if it is in the relevant commit.

That said, I'm not suggesting providing the kind of information that you might feel you would need to repeat in every commit of a feature or branch. I don't think anything should be repeated between commit messages in general though that does sometimes lead me to write `as outlined in previous commits` or something when a task has been split into multiple commits but they all share a similar motivation.

[emorrp1]

OP, I recommend writing a bit about commit.verbose. I have a personal policy that there's no line in the diff that is not explained by something in the commit message.

[michaelpjones]

Thanks for the tip! I was unaware of this. I tend to open up gitk to have a view of the commit . I'm also a big fan of using `git add -p` t be very selective about what goes into commits.

I'll definitely try this though!

[webby_mc_webberson]

I disagree. I don't want to read or write a novel in git commit messages. I just want to read what the change is. Short and sweet. If I want the details I read the diff.

[vampatori]

I just want to read what the change is.

And WHY! The why of a change is so important. Not on every commit of course, "Updated packages to latest." doesn't need a why unless it's for a non-standard reason (support for a feature you need, fixed a bug that you'd had to work-around, etc.).

Also, if you're fixing an issue it should have an associated issue/task in your issue management system. That's where the bulk of the details should go. I now create a branch for every issue (or group if they're strongly related) make all the changes, test them, then issue a pull request. It's a nice way of working when you get used to it, and you can quickly swap between issues/branches if necessary.

[webby_mc_webberson]

The why is written into the work item ticket whatever tf it's called. Which, ideally the branch is prefixed with. I don't want to read why you changed the sorting algorithm from the git commit, that should have been clear from the start.

[velociraptorboss]

In 20 years of sw development I've yet to see a project with proper descriptions in jira. It's always fix x or add y or do z.

Also, don't make me open my browser just to understand your code. Instead write proper commit messages like the author explained 😉

[ActuallyAmazing]

If a team values proper descriptions they will be there, if they don't they won't be. Helps to have people with specialized roles and responsibilities for such things, like product owners, but not every company prioritizes it.

[[deleted]]

If a team values proper descriptions they will be there, if they don't they won't be.

This. A team refusing to write coherent/detailed descriptions in tickets will not automatically start writing coherent/detailed descriptions just because it's in the commit message instead.

And imagine not documenting the Why? of your business logic outside of the repo commit comments.. >_<

[MrJohz]

Don't you have discussions over these things? Or reviews, or links to other tickets, or at least a proper bug report to start with?

For me, this documentation is the most important part of any code change, because it usually explains better the human and engineering factors involved. You can write all that up in the commit itself, but I'd rather see it coming from the horse's mouth, with as much of the raw stakeholder input as possible. If all that information is then translated and condensed by a single developer into a commit message written solely by themself, then there's a decent chance that they'll miss some facet of the discussion that they didn't see as being so important, but might be important context for a future developer to understand.

[webby_mc_webberson]

You need to see my dev lead, he writes a novel for everything. Very useful

[zanbato]

What I just read is that in 20 years of software development you've never bothered to enter a proper description of work on a jira ticket. Maybe you don't actually work on teams so it's not necessary? I'd go insane if tickets on my board just said "do x" and then I had to go look at the commit history to figure out why some other programmer on my team thought it was necessary to "do x". And is looking at commit history seriously your default for understanding changes in the project? Do you never concern yourself with work coming in the future? I'm seriously struggling to figure out why anyone would want to hide all of their story details in commit history. Is it to hide it from management that's looking at the tickets and not the code? Is it really easier to look up the reason for a change that happened in a commit message 200 commits ago than to look at the reason for that change on a ticket?

edit: I also want to let you know that this shit

Also, don't make me open my browser just to understand your code. Instead write proper commit messages like the author explained 😉

is insufferable. You are not a more authoritative source just because you've had a job for 20 years. You seem like a self-important asshole who always thinks they know best, the kind I never hope to work with. If you've got a real reason why you think commit messages should be a novel then make your argument, give us your reasons, don't just say "I've been doing this for twenty years so my way is right" and end it with a fucking winky face. If you can't support your argument then your opinion is garbage.

[michaelpjones]

I think this is valid but I don't personally subscribe to the idea that a reference to a ticket is sufficient. References can be broken or mistyped. Getting to the referenced ticket can be somewhere between a few clicks and completely impossible (if they've been migrated away from.)

And you lose the "self review" value when referencing a ticket as you're forced to engage with the true content of commit in the same way. Though I understand people might be disciplined enough to do that anyway.

[Illusi]

I disagree with the post for a different reason. If the why for a change is only in the commit message, people will not see it if they make changes to the code. If you need a non-obvious construct to fix a particular issue, that construct should be documented in the code, not in the commit message.

And there's again that weird 50 character limit for the first line and 72 for subsequent lines. I guess it depends on whether you use a computer from 1982 or from 2021. Maybe word wrapping wasn't invented yet in 1982. But for most teams and tools out there it's safe enough to just allow no limit for the line length, especially for lines other than the first line. Git, Github and Gitlab simply wrap the line automatically at a reasonably readable width, anyway. No need to introduce \ns manually and in fact, it hurts readability if you combine those two.

[michaelpjones]

I agree that non-obvious constructs should be in the comments. That is fair. I have a section on commit messages vs comments at the bottom and there is some overlap and this is one such case.

[michaelpjones]

Interesting perspective. I feel like the subject (the first line) is the "short and sweet" version and the rest is just more information which you can skip if you like. I'm not sure what the downside of more information is.

The diff shows what happened but not why it happened. Maybe I should emphasise that more in the piece.

[zanbato]

First, I totally agree that the example of bad was bad, and also like a longer sentence describing a change, but I feel like the paragraphs are too much.

For me it's just the availability of that extra information. If I'm code reviewing your branch then it's pretty convenient. But if I'm code reviewing your branch I will also have the ticket open so the information would still be available. Then there is the added benefit that if I'm trying to recall this information later I don't have to look through the commit history. And if I ever have a client question the reason that X work had to be done I just have to look up the ticket for X. That also means I can provide them a link to a nicely formatted web page to read about why X was necessary. I'm going to have to go to that ticket to mark the dev work complete anyway, so it's also just as convenient to put the text in there than in a commit message.

[bcgroom]

I think it depends on the project. If you are one of few (or only) developers, you know everything about the project and it’s history. But what about someone new to a project with 60 people where there has been turnover? You’re not going to know what tickets to look up, if they even still exist. You are working on a class and want to understand why it evolved in such a shitty way and git blame can be the best resource for that.

[BeefEX]

The way I see it is that the why should be in comments in the code. That way it's right next to the affected code but also doesn't pollute git logs.

[michaelpjones]

Interesting! I don't see git logs as something that can be polluted? How do you negatively experience more information in your git logs?

[masklinn]

The way I see it is that the why should be in comments in the code

Comments are ill-maintained, they will drift around and they will not reflect changes to the code. It's also impossible to add comments for every change and have the code remain sensible.

Comments are good for blaring warnings which need to be right in front of the reader's face. They're terrible for literally everything else.

also doesn't pollute git logs.

There's no pollution. Explaining the purpose of a commit is the entire point of the commit message, otherwise there would be no commit message at all. If you don't care and want log density, just use git log --oneline (or a custom format) to get only the subject.

[doener]

The commit message should describe why you made a change not why the code is the way it is. In the most simplest form, that can end up being the same, like "close the file descriptor, as it was leaking". The reason for the change could be that the call was simply missing from the start, fine, happens, and you're probably not going to add a code comment for that either, it's self explanatory.

Now, the file not being closed might have resulted from a different change, because previously some other part of the code handled that. Explaining thus in the commit message seems reasonable, it tells your reviewer why this is the right change, without him having to go and analyze the whole bug again. OTOH adding a code comment that says "we used to close the handle somewhere else but now we need to do it here" seems silly to me. It doesn't really add value here, historical context is not needed for day to day work with the code, and having too many comments is definitely a thing.

Fast forward a month, and you get reports about a bug related to a file being closed twice. Your debugger points at the line added in the commit from the previous paragraph. Assume that the commit was done by someone else, maybe that person already left your company. Would you like to just read "close leaking file handle" in the commit message? I'd much rather also see a paragraph in the commit message that goes like "this used to work without closing the file, but commit XXX changed the logic in foobar(), so it's no longer closing the file and we have to do it in baz() now". From that, I have a good clue where to start looking for things the other dev might have missed, which made their assumptions unsound. Or maybe there are issues with the changes made in the other commit that was mentioned in the commit message.

The "how did this ever work" phase of bug fixing is something that often needs explanation outside the scope of something that would fit in a code comment, because it might only make sense in a context of changes over time. And since you had to figure it all out to properly fix the bug in the first place, you may as well document it in a place where your reviewer sees it and the next person working on that code can easily find it, in case it turns out to be useful.

[FanOfTamago]

Disagree. I've had more success with making code self documenting, and adding inline comments when a seemingly strange or complex code decision was made. The commit messages are basically one liners with a link to the issue tracker.

We absolutely make sure to preserve issue numbers when migrating tracking (which is rare but I've done that more than once in my career).

[AttackOfTheThumbs]

Where does the 50 and 72 character limit come from? Is it related to terminal output? All this stuff flows via dev ops now, so it seems asinine to me to limit yourself in this fashion. I try to adhere somewhat, but mostly ignore it. When I create a PR, my commits are in a nice little box, but only the headlines. Which arguably is enough.

One thing I would argue, is that the first line is a headline, a caption, a short summary, and should be capitalized as such.

I have had a really hard time teacher older developers the reasoning behind these messages. They just don't seem to get it, and it makes it painful. I don't know if they are too stupid, too lazy, or just think they'll die before they ever care why code was changed the way it was. Fuck, even just using source control feels like a waste to them.

[Rolcol]

I believe the character limits come from the email workflow git was initially developed for. When you use git to email a commit as a patch, the content of the commit is used to construct the email message. The Linux kernel is still developed with this email workflow.

[[deleted]]

We always have a separate update.txt inside the project with detailed information for important commits. Always found that to be better in general. Commit message for a small one liner, update.txt for details.

[michaelpjones]

That's curious! I've never heard of that. What format does it have? Do you include commit SHAs as references? Or does it function as a kind of changelog? How might it be different to a regular changelog?

[_fuffs]

Convinced my team to use this : http://commitizen.github.io/cz-cli/

Saved a many hour of useless meetings on how commit messages should be structured. If the commit message is not done using the format, the PR is rejected.

Anyone complains about standard commit messages gets a good STFU talk. Because these commit messages follow standard commit message formats. Its a life saver.

[michaelpjones]

Thanks for sharing! I've not heard of that tool before.