Tim Pope

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…

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."

> 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

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/

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...

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