9 ms·
Using Git commit message templates to write better commit messages
- urxvtcd 5y agoI like to include the following line in my template: # Co-authored-by: Firstname Lastname <f.lastname@company.com> so I can quickly uncomment this and fill in the name of the person that helped to author the change. It even is recognized by gitlab and github.
- jasonpeacock 5y agoThis is a good idea, but in practice after a few commits you learn all the principles and don't need a wall of text in your commit template. Getting feedback in your PRs about your commit messages helps quickly reinforce learning these best practices. (you do review the commit message when doing PRs, right? ;) I'm a big fan of Conventional Commits[1], so my commit template reminds me of the types and provides an actual template to describe my change: <type>(optional scope): # type: build ci chore docs feat fix perf refactor revert style test Problem: Solution: Testing: Issue: Where Problem describes why this change is needed, Solution is what this change delivers, and Testing is how this change was validated. Issue is the JIRA/Github issue related to this change. EDIT: The Problem/Solution/Testing/Issue is not part of Conventional Commits, I added those to give structure to the body. [1] https://www.conventionalcommits.org/en/v1.0.0/ https://www.conventionalcommits.org/en/v1.0.0/
- JoelMcCracken 5y agoI also like the problem/solution format, it gives a ton of context.
- tekno45 5y agoisn't the problem described in the jira ticket?
- throw0101a 5y ago> isn't the problem described in the jira ticket? Yes/perhaps/maybe, but it's nice to (a) have it in front of you without having to change programs or context, and/or (b) have it summarized, as the ticket may have 'extraneous' stuff like a bunch of back-and-forth with the user/client/tester/etc.
- erik_seaberg 5y agoOrganizations ought to preserve tickets across migrations to new systems, but they don’t always. Only commits are forever.
- icedchai 5y agoExcept tons of orgs squash before merge (unfortunately, IMHO) so individual commits are pretty transitory. Doing “conventional commits” for all those smaller commits seems wasteful.
- terinjokes 5y agoThey often believe they'll never change ticket systems. Until they find out one morning IT didn't subscribe to the same ideology.
- luxurytent 5y agoNice to have the problem in line because I can search git history. Also no guarantees that the Jira ticket will be around as long as the code.
- Liquid_Fire 5y agoThe problem the commit is addressing might not be exactly the same as the problem in the JIRA ticket (e.g. you're solving a bigger problem than just what the JIRA describes, or there are multiple causes and this commit fixes only one of them, etc).
- antman 5y agoWe have a: What Why How Related
- Octabrain 5y agoI’m a big fan of Conventional Commits specification too. I always been strict with myself when writing commit messages, but I have members of my team that were a mess. So, it’s good for establishing a clear pattern for everyone to follow. Also, by implementing it, you gain a lot of flexibility in terms of the interaction of your code being pushed and the CI/CD pipeline. (e.g auto release generation with semver) The only “bad” thing is that I feel some of the <type> standards don’t fit very well for certain cases that are not exactly distributable software. (In my case, devops, committing to a TF project we own: mmmm is this a “chore”, a “feat” etc)
- brundozer 5y agoI've always seen conventional commits as an anti-pattern as it seems to discourage developers from writing small, atomic commits. I think that a commit should always be as small as possible and have a descriptive, meaningful message. It is therefore pretty common that I end up with tens of commits when working on a simple feature. Which of these commits should be labelled as "feat" when the feature is added by a group of commits rather than a specific one, and that none of them really adds any feature? Also, a bug can be fixed by many commits. Which of these commits should be labeled as "fix"? We can't label all of them as fixes as cherry-picking only one of them wouldn't fix anything, which means the commit message would be misleading. The only solution left is to create one commit per bug fix or per feature. Moreover, this information can (and should) be carried by the branch name already, as you'd usually branch off from your main branch to either fix a bug or develop a new feature. All you have to do is to follow a naming convention for your branch like "feature/my-awesome-feature" or "bugfix/fix-this-annoying-bug". The only benefit I see with using conventional commits is generating changelogs automatically from your git history.
- jasonpeacock 5y agoConventional Commits restricts each commit to a single type of change - no mixing bug fixes, features, and refactoring. This supports exactly what you want - small, atomic commits. Why can't each small change be labeled "feat"? A feature does not need to be contained in a single change as a "big bang" commit. I make multiple "feat" changes to deliver a feature. I follow trunk-based development[1], so branches are many, transient, and disposable (and sometimes not even present if it's a small change I'm pushing straight to `main`). The advantage of Conventional Commits is that I can go to my trunk (`main`), and scroll through the list of commits and see their purpose at a glance: feat: ... feat: ... build: ... fix: ... feat: ... chore: ... I can immediately tell which changes were related to fixing the build, or a bug, or supported feature development. [1] https://trunkbaseddevelopment.com/ https://trunkbaseddevelopment.com/
- gknoy 5y agoI nearly never look at individual commits in a PR. I realize that this isn't applicable to all codebases, but when troubleshooting why a bug happens, or was intended to work, I find it a lot easier to look at a squashed commit than at the individual commits that went into a pull request. It does make `git bisect` less specific (and, to my shame, I've never used it), but having an overall commit message + pull request that points at a Jira ticket (or similar) helps identify whether something was intended behavior or not, and I've never felt the need to look deeper at whether part of it was a refactor/chore/feature. (If I had, I could look at the PR branch, presumably.) In contrast, I've often had a stream of a 12-20 commits with tiny atomic (and often terrible) messages like "bugfix", "add test", "fix test", "fix linting", which I then try to rebase into some _coherent_ messaging of the time you espouse, where linting + typo fixes are rearranged and squashed on top of the commits that added them, and tests + features are added more closely together. It's very satisfying to do this, but in retrospect I've always felt like the time I spent doing that has been wasted --- it's hard, and often involves many iterations of conflict resolution when reordering commits, all for something that I or my team will squash anyway. The benefit gained (more readable commits of temporary value) never ever seems worth the time (Multiple hours) put into making them that way.
- gwd 5y agoI hadn't seen Conventional Commits; my in-head template looks very similar, with the addition of a "Situation" before the "Problem". On a big project, the reviewer may not know (or may not remember off-hand) exactly what the code does at the moment. So saying, "The code currently does X" is a helpful prompt, so that when they read "That's a problem because of Y", they have all the key context in their head (rather than perhaps having to guess and/or look at the code to figure out what's going on).
- _ZeD_ 5y agoPlease - be aware of what you're doing relying on conventional commits. I saw projects using them to later do automatic merges between branches, and I think this is the "wrong level of abstraction". I think there is an underlying problem if you are mixing "fix" and "feature" (for example) commits in a "feature" branch. Why the fix is in a feature branch? I think it's more important to have the distintion on a "branch" level, linked in a 1-1 relation to a jira/feature/bugtracker issue and whatnot.
- jasonpeacock 5y agoNow you're talking about branching strategies, not commits, which is a different and much larger topic :) I keep it simple - branches are short-lived. I don't even like feature branches, I break features into a series of changes and push each change to `main`, incrementally delivering all the changes needed to make the feature useful while keeping `main` healthy. More details at: https://trunkbaseddevelopment.com/ https://trunkbaseddevelopment.com/
- wodenokoto 5y agoI like it, but I feel like it is closer to a merge request message / merge / rebase commit message. Generally I think it is good form to break down your stories so they match the scope of a reasonable merge request and name the branch [issue-id]-human_readable_text
- jakeinspace 5y agoAgreed. I can't imagine working on a feature branch and writing 50 of these for a moderately large change, just for those to be squashed. I mean, I can, but I don't think it's necessary.
- charcircuit 5y agoIt that case you can put in the detailed commit messages later. So when you are doing your squash you type in the detailed commit.
- mnahkies 5y agoI wish that github would stick multiple commit messages into the default pr body - if I have a single commit it'll prefill the pr body from its message, but have a series of commits it won't. Should use the same rules as it's default squash message IMO
- kevincox 5y agoGutHub support for reviewing multiple commits is basic (to be generous). The focus is all on the "PR" the entire diff and the description (that lives outside of git). I think this is pretty harmful to having a useful git history and a conspiracy theorist would likely say that it is intentional lock-in.
- mnahkies 5y agoI'd love to be able to browse pr's commit by commit marking files as viewed, and then ideally have this bubble through to the holistic change view
- teeray 5y agoMy commit messages usually just try to answer the prompt “why does this commit exist?” That’s because future me will be asking that when I open the commit after finding it in `git blame`.
- deleted 5y ago[deleted]
- thot_experiment 5y agomy commit message template: "[profanity], wow this has been sitting for [number of months] with uncommitted changes that i don't remember the purpose of, committing so that if i break more stuff i have a point to roll back to"
- NetOpWibby 5y agoMy messages tend to be: “Progress”
- infogulch 5y agoThe prompt that I use in my head is finishing the sentence "Applying the diff in this commit will...". Examples: Change the submit button color to green Bump library XYZ to 1.2.3 Refactor and simplify the cart repository
- deleted 5y ago[deleted]
- spartanatreyu 5y agoThe problem with that is you'll start reworking on a part of a project then you'll find something in the code and say, "Why was this done this way? It'd be so much easier just to do this instead." Then you'll investigate further and find the commit that made the thing, read your commit message above and say, "Okay, why did I change this thing? I'm guessing it solved a problem at a time, but I don't know what the problem was." You'll decide: "I'm just going to pull this out and replace it with this easier thing". Then everything will work except for one thing, and you'll end up wasting days trying to sort out a weird corner case. Part way through that you'll come up with a solution that is more complicated then the easy refactor you tried to make and at some point you'll think, "Oh, that's why that was like that". You could have saved 3 days of work by just spending an extra 30 seconds to write the "Why" in your commit message. Your commit already includes the code changes (the "What"), so put a one/two sentence "Why" in your commit message.
- TAKEMYMONEY 5y agoA noble effort but in my experience these just get ignored. 90% of the PRs at my org have the empty, unfilled template text at the top of the description, a few line breaks, and then the actual description underneath.
- yakshaving_jgt 5y agoThat's unfortunate, and I think your experience reflects most places I've worked at too. It doesn't have to be that way though; technical leadership on a team can choose to care about this kind of thing and coach their colleagues into caring more about writing communicative commit messages. To any technical leaders reading this comment, I encourage you to choose to care about this :) Here's the post I always share on this: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html https://tbaggery.com/2008/04/19/a-note-about-git-commit-mess...
- gaoshan 5y agoWe immediately kick them back if this is the case.
- jasonpeacock 5y ago1. Implement automation to flag and block/reject bad commit messages. 2. Educate and train ppl to include commit messages when they do code reviews or 3. give up and move on because your org doesn't care. Because this is a culture (not code) smell and changing culture is hard and needs support from the top.
- toomanybeersies 5y ago> Implement automation to flag and block/reject bad commit messages. They'll just use `git commit -n` to skip the pre-commit hook. And if it's verified in CI (e.g. with Danger), someone will just create a script to automate writing commit messages that pass the good commit message test.
- jasonpeacock 5y ago
- woodruffw 5y agoI had no idea `git` supported a template for commit messages. Very cool! It doesn't enforce Conventional Commits, but I use this[1] to lint my commits in conjunction with a Sublime Linter plugin[2]. [1]: https://yossarian.net/snippets#git-lint-commit https://yossarian.net/snippets#git-lint-commit [2]: https://packagecontrol.io/packages/SublimeLinter-contrib-git-lint-commit https://packagecontrol.io/packages/SublimeLinter-contrib-git...
- einpoklum 5y agoMy approach is to reserve the verbose discussion for the issue tracker and then keep the commit message short with "fixes #NNN:" and a short description of what's changed without motivation, design considerations etc.
- splix 5y agoI'm a big fan of problem/solution format. I.e. something like _"problem: suboptimal routing for upstreams in different datacenters; solution: additional role to separate primary and secondary upstreams"_. Also I consider commit message as a message to someone who would deal with that piece of code maybe years from now. And he would wonder why these lines even exist, and if he can replace them with some new logic.
- Scea91 5y agoFor me, commits are too low granularity. I usually give 1-2 sentence summary. I put detailed descriptions (sometimes multi-page with graphs and tables) into pull-requests. I understand that for projects with hundreds of collaborators the needs are different. But in our project with a team of 8 people I feel the overhead of structured commit messages is not worth it.
- dpifke 5y agoPull requests are trapped inside Microsoft's proprietary platform (Github) and viewable only on the web for as long as Microsoft sees fit to give you access. Good luck getting that history out if your Github account is ever disabled for any reason. Commit messages are part of the repository itself, meaning they're replicated (backed up) locally every time you pull. They can be viewed using any tool that operates on Git repositories, e.g. https://magit.vc https://magit.vc.
- gbear605 5y agoAt least with Gitlab, the text of the merge request is used for the text of the merge commit that’s created when you merge in the changes, so the comments still get added to the Git history.
- anchpop 5y agoIt would be nice if pull requests and issues were integrated into git somehow, to avoid centralization like this.
- wodenokoto 5y agoI haven’t tried it, but it is my understanding that the source code version control system made by the SQLite team does this.
- Too 5y agoGerrit avoids this problem neatly by not having any PR message at all, the only place you can provide context is the commit message, which obviously gets tracked together with the repo. Review comments are stored out of band though. Curiously in another hidden git branch of the repo.
- jph 5y agoGood work! Here's our git commit template which we use with tags for categories, keywords for searches, links to issue trackers, etc. https://github.com/joelparkerhenderson/git-commit-template https://github.com/joelparkerhenderson/git-commit-template
- Noumenon72 5y agoDoes anyone else use these kind of trailers like you do? # See: https://example.com/ https://example.com/ # See: Issue #123 <https://example.com/issue/123 https://example.com/issue/123> I have been putting the issue number at the start of the title so I could see which commits were related, but it seems like people would not want to do that with a 50-char subject line.
- jph 5y agoYes optionally, because trailers with links can be especially helpful when a commit is relating to specific URLs, such a relevant blog post, or design image, or planning document, or industry publication, or committee RFC.
- fouc 5y agoHow large are your commits to need templates? Should a feature branch always be squashed into one commit before PR?
- deleted 5y ago[deleted]
- OJFord 5y agoAs long as it says why not what (and in which case inherently doing a worse job of it than the code) it beats the vast majority IMO!
- greyface- 5y agoA useful, related trick. Enable commit.verbose to have Git append a diff to the commit message template, which you can quickly consult when writing a commit message. git config --global commit.verbose true https://tekin.co.uk/2020/03/git-commit-verbose-mode https://tekin.co.uk/2020/03/git-commit-verbose-mode
- yjftsjthsd-h 5y agoThank you; here I'd been using an alias for `git commit -v` all this time:)
- bin_bash 5y agowow thanks for this! I often find myself amending after running `git show` to get this information
- chrismorgan 5y agoA related thing of Git settings: if you ever want to start a line with #, change core.commentchar to something else. I use a semicolon. (`git config --global core.commentchar \;`) Also your text editor may be able to help with things like 50 and 72. Vim’s gitcommit syntax and ftplugin files, for example, highlight the first 50 characters of the first line differently and set textwidth to 72, so that if 'formatoptions' includes t it’ll auto-wrap as you type, and you can use the likes of gqap to rewrap a paragraph. (If you change commentchar, you’ll want to copy and change those files to match. Hmm, should contribute a patch to make it configurable with a variable. Probably won’t get to it, though.)
- kevincox 5y agoI prefer scissors. https://git-scm.com/docs/git-commit#Documentation/git-commit.txt-scissors https://git-scm.com/docs/git-commit#Documentation/git-commit... This way you can use basically anything at the start of the line (as long as the whole line isn't the scissors)
- chrismorgan 5y agoThe really funny thing here is that I’m used to seeing the scissors line because I set commit.verbose, but I’d been puzzling from time to time over what that >8 in the middle of the line was, and just a few hours ago I finally realised (prompted no doubt by dwelling on core.commentchar) that it was ASCII art scissors. >8 feels weird, even though it’s the direction a right-hander would cut paper; 8< feels more natural for some reason (maybe because LTR language?). You’re quite right, scissors is better. TIL! I have now set my commit.cleanup to scissors. I could even drop core.commentchar and my gitcommit and gitrebase syntax and after/ftplugin/ patches.
- dkbrk 5y agoI hadn't hear of the 50-char recommendation before, just the 72-char limit. In Emacs, magit and git-commit-mode accommodate this well, I just found. Setting git-commit-summary-max-length to 50 and fill-column to 72 has the behavior that a visual warning will be displayed if it goes over 50 chars but it'll only wrap at 72. The body also wraps at 72, of course.
- kevincox 5y agoHard-wrapping is a mistake. It seems like you can keep making the line-length shorter to make it like likely to run into the double-wrapping problem but the best solution is not to wrap and let the viewer wrap at their preferred width.
- pictur 5y agoWhat advantage do long commit messages have? In most open source projects, commit messages are very short. however, it is extremely easy to follow the progress through history as the code changes are always kept less comprehensive. but I would like to listen to the advantages of writing long commits.
- Liquid_Fire 5y agoI can't speak about it in the context of open source projects, but here are some general benefits: * Easier for your reviewers to understand the context of the change => easier to review the code (I think this alone makes it worth it) * Keeps you accountable to yourself. By clearly describing the problem and the solution, it gives you an opportunity to spot when you're solving the wrong problem, not solving the whole problem, or solving it the wrong way, or including unrelated changes in your commit. * Provides historical context. Sometimes over time the purpose of a particular part of the code becomes less clear, but with git blame you can immediately see it, assuming the commit message describes it well enough. (Yes, ideally the code will speak for itself or be supported by comments, but we don't live in an ideal world - and the comments may not be in the part of the code you are reading) * Teaching opportunity - e.g. "we use approach A because the more obvious approach B has problem X" (again, sometimes better captured in comments, but not always)
- ransom1538 5y agoI use this one from "How To Write Unmaintainable Code". /* /* Procedure Name: /* /* Original procedure name: /* /* Author: /* /* Date of creation: /* /* Dates of modification: /* /* Modification authors: /* /* Original file name: /* /* Purpose: /* /* Intent: /* /* Designation: /* /* Classes used: /* /* Constants: /* /* Local variables: /* /* Parameters: /* /* Date of creation: /* /* Purpose: * /
- marginalia_nu 5y agoYou should just fill out a TPS report instead.
- mns 5y agoI'm reading the comments here and thinking I'm some outdated greybeard. Do people actually spend more time now trying to write commit messages than doing actual work? I would never put any of my teams to do something like this, do actual developers LIKE spending more time to actually write these messages? Is code today so hard to understand and read (what about comments) that you need these things for reviews?
- marsven_422 5y ago
- anshumankmr 5y agoIf I had a dollar for everytime one of my team mates wrote a commit message as "Fixed the bug" or "Update filename.js", I would be quite rich.
- PennRobotics 5y agoSomeone in my organization (senior to me) often commits with the message "progress"
- catinblack 5y agohttps://mokkapps.de/blog/how-to-automatically-generate-a-helpful-changelog-from-your-git-commit-messages/ https://mokkapps.de/blog/how-to-automatically-generate-a-hel...