Tim Pope

If the wording of the commit message is the issue, there are ways to reduce the toil without having AI confabulate a message. Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/> has been discussed on HN many times. The 50/72 practice (some tools will help with this) <https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html&… and many many words out there suggesting some best practices. A team can and should work out their own best practices. A git prepare-commit-msg hook can provide a template for message conventions. Perhaps there's room for a tool or UI enhancement to provide additional guidance.

For programming, I've found that my time spent navigating the code dominates the time I spend editing it. Bram's recommendation is to generate a tags file right away for every project to keep this time down, and it's excellent advice. The problem with this, however, is that it's a pain to remember to generate and update the tags database. Thankfully, you can configure Git so that it builds a tags database for you automatically whenever you clone a repo, and updates it in the background every time you commit, pull, or push. Instructions here from Tim Pope: http://tbaggery.com/2011/08/08/effortless-ctags-with-git.html I'm partial to GNU Global, myself, which adds a basic "find references" command, slightly better parsing, and incremental DB updates. Also relatively easy to set up for effortless navigation: https://csl.name/post/gtags/

My personal favorites on the topic: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-messag…

Here's what, Tim Pope, our favourite vim nerd has to say about this: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html (Same, but with more words.) A point of contention seems to be the choice of the imperative, at least for the subject line. While I'm really used to it, both when reading and writing, many people seem to strongly prefer past tense ("Fixed bug …" instead of "Fix bug …").

It appears to originate with Tim Pope: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Reading between the lines, it seems that the 50 character limit is to accommodate commands like "git log --pretty=oneline" and "git rebase --interactive" on an 80 column terminal. He also recommends 72 columns for any subsequent text because git makes a left margin of 4 characters and it looks balanced if you also have a right margin of 4 characters (80 - 8 = 72). As someone who actually uses an 80 column terminal, I appreciate this practice. Probably younger people with good eyes won't be able to understand the reasoning behind it ;-)

great. next up: a well-written & concise guide on writing proper commit messages. could be based on http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html and http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message

Tim Pope has written about the model commit message [1] and why you should use a short first line, I'm a big believer in this setup and it's done wonders for the readability of my commit messages. Github itself even uses these rules [2] so I think it's slightly annoying people don't follow them as it looks worse if you use long first lines on the website. [1] http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html [2] https://github.com/blog/926-shiny-new-commit-styles

Git best practices say the first line in your commit message should be no more than 50 characters. Subsequent lines should be wrapped at 80 characters. See http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

as davvid says, the git project is an excellent place to start. The git project inherited a lot of its practices from the linux kernel project, but they are different enough to make looking at both interesting. The archive for the git list is at [1]. The other great thing to look for is a well designed standard, with examples, for how a commit message should look. Most everyone who uses a standard uses The Standard* [2], so I would suggest you do the same. * Except that many projects don't require the sign-off [1] http://dir.gmane.org/gmane.comp.version-control.git [2] http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html (I am pretty sure there is a very similar post from Linus on a mailing list somewhere, but I can't find it. This is the most commonly linked to that I could find.) [EDIT] formatting...

nice, but the example on the homepage doesn't follow the git commit message guidelines[1]. it would be nice if you could fix that, so as to not spread bad practices any more than they already are. [1]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

In my usage, the story is for myself first and foremost. Telling the story helps keep me organized and helps me remember what I've done and where I'm going. I don't need to know that I fixed a typo in a comment, I need to know what the changes are overall doing. Sometimes I go down a dead end, reverse out, and leave a comment about why a different approach would be a dead end. I (and others) don't need a record of the work I did on that path, just the synthesis (an explanatory comment) There are multiple systems for structuring commits, but the commit message body content approximates to the same in all of them. The classic advice is https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html , but I find https://www.conventionalcommits.org/en/v1.0.0/ useful for looking at the oneline log To address this point: > To checkpoint units of work as individual perceives them, helping them deal with interruptions (which include running out of work day). Yes, commits can be used like this! But once you have a chunk of work ready for review, cleaning up the commit log/history, grouping related changes, and describing them is useful for maintaining the software. I don't like squash merges personally, though they have their merits. But regardless, I would copy the commit subject/body content into the PR message, which then puts everything into the PR commit also, so technically the granular commits are less relevant when one merges, but occasionally are still useful to…

> I've been debating starting to include it in my code reviews: "this commit log needs more details: can you edit the commit message and do a git push --force?" Strongly agree with this. I hold the line on this for every team I lead (which, sadly, is not every team I consult for, so sometimes I have to keep my mouth shut and spend my political capital elsewhere). Many junior/mid-level engineers have simply never seen commit messages and source control done well. Additionally, because many folks starting out in the field don't know how to truly use git beyond memorizing a few basic commands [1], they also never harvest any of the benefits of writing great commit messages. I've got a stash of links that I find myself often sending to engineers who are on the way up, and the tpope article on git commit messages [2] is one I find myself sharing around constantly. [1]: https://xkcd.com/1597/ [2]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

I'm quite fond of vimscript legend Tim Pope's guidance on writing commit messages. https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

72 characters per line is a common standard for git commit messages. If you use vim, the syntax highlighting will nudge you to exactly that number. https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

That'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-messages.html (2008)

My main feature request would be a way to enforce a PR must be a fast-forward merge. I tend to have a small set of words I prefix each git commit summary with (Add, Remove, Fix, etc). If I could verify summaries match that pattern that would be awesome. Also, if it is possible to enforce the guidelines specified in http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html I'd be so happy.

When using Git's mail features -- remember, not everyone uses GitHub -- the first line of a commit is a subject line. It's good practice to just think of it that way. If you write sentences in your subject lines in e-mail, I guess, that's up to you. Don't take it from me, read the Tim Pope counterpoint, with eight extremely good reasons for concise subjects in the closing paragraph: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Strong disagree with antirez on this one. Even vim filetype gitcommit disagrees. (Try it on the "smart synopsis" example.)

Old, but still valid: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

I believe the motivation is explained here - http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.

Yeah, they miss this in several examples ("updated", "added", "fixed"). I know where you're coming from, it feels more natural because when you ask yourself "what did this change do?" to write the commit message, the answer is in past tense. They fail to mention the reasoning behind the convention, which dates back at least to tpope's 2008 blog post[1] and is also in Documentation/SubmittingPatches in Git's own repo[2], which is that not only does the imperative tense tend to be slightly more concise, but more importantly, it's consistent with automatic commit messages generated by commands like git merge and git revert. [1]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html [2]: https://github.com/git/git/blob/master/Documentation/SubmittingPatches

This is probably more on point--"A Note About Git Commit Messages” http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

I don't like the idea of your gg function, but I add files to the index using git add -p exclusively since it gives me a chance to review my changes as I'm adding them, as well as let's me ensure I split up different logical changes into separate commits. Likewise, I think git commit -m encourages lazy git commit messages (see: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) Mostly because this helps me keep a clean history, which is something I value highly.

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html gives a good description.

According to http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html (linked in one of the comments in the github discussion) it is for consistency with the commit message generated by 'git merge' and the like.

Ok, found this, linked by Mr. Torvalds http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

This is a good post about readable commit messages: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

See http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html, http://gist.github.com/539516 etc.

Tim Pope explains why it matters: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

The first comment: "Every source control management system has its own rules. So what I say here for Git might not be valid for Mercurial, SVN, Bazaar, ... "Git has a wonderful tool named format-patch, http://git-scm.com/docs/git..., that takes a commit and converts it to an email, to put it in a nutshell. Why is there a tool for that? Because Git was created to manage Linux kernel development, and that is done in most parts in or around the Linux Kernel Mailing List. So, the entanglement between commits and emails is deep rooted in Git. And yes, the first line of the commit message _is_ used as the subject. "This explains, why you can google "git commit message" and find the same advice over and over again: "http://git-scm.com/docs/git...* "https://github.com/erlang/o...* "http://tbaggery.com/2008/04...* ""No dot at the end, because it might end up as email subject, also use 50 chars or less."* "I agree, that interpreting it as title for a longer commit message is a bad idea. The conciseness of this line is something important to be retained. A well-crafted email subject on the other hand makes in some cases reading the whole email unnecessary or only complimentary. (Yes, such things exist.) And that are the types of commit messages that we should strive for, ending with a dot or not."