Skip to main content


I've got a new blog post up at Meedan (where I work). It's about longform git commits: what they are and how they can make your life as a software developer easier.

My spiciest git take is you should ban "-m" from your git repertoire and go full verbose invoking a text editor from the CLI to write commits.

https://meedan.com/blog/how-to-write-longform-git-commits-for-better-software-development/

reshared this

in reply to Darius Kazemi

To answer the eternal question "what on earth were they thinking?"
in reply to Darius Kazemi

What I like about this is that it combines good editing practice in multiple layers.

The first line (what you're calling the subject line) of a git commit message really aught to be a simple "<verb> <subject>", but then you're right that there's room for more detail.

I'm still struggling to get some devs to perform good commit messages.
in reply to Darius Kazemi

Weird take: I very occasionally use -m with mercurial (I believe single line commit messages are almost never a good idea, but sometimes I do things that are not a good idea) but I NEVER use -m with git because it is completely baffling to me what files do and don't get included on any one git commit and entering the editor is the one surefire way to be CERTAIN you know what it is you're committing...!
in reply to mcc

Yeah that is one of the main reasons I avoid -m so that tracks. Cool that mercurial does not share that problem.
in reply to Darius Kazemi

I can't write a commit any more without using commit -v, it's so good
in reply to vx. size_t queen grace :qvp:

I'm legitimately a bit confused because I never use -v, I just use `git commit` and the diff pops up in my text editor ready for me to write a nice verbose commit message, as is my wont. Do people routinely change repo or local settings to make `-v` necessary?
in reply to keithzg

Ohhh sorry I see, the *full* diff. I suppose variable autocompletion would be nice! I tend to trawl through `git diff` as a step beforehand so seeing the specifics of the diff didn't even occur to me, heh, whoops.
in reply to keithzg

Absolutely do the 2 or 3 tier approach to my commit messages as described here, with the modification that I generally acquiesce to the standard form at my work where we put the bugtracker issue ID at the start of a commit. Unfortunately most of the computer engineers at my work will put *just* that issue ID with maybe some very terse "description", like

> BugID:999 - Commit fix

which means reading back through the commit log *requires* cross referencing our bugtracker.
in reply to Darius Kazemi

I wish I could convince people to quit using `-m`. Whenever I run Git workshops at work, I try to motivate the use of your Git logs as documentation and why you should go ahead and open up a text editor for your commit message.

I don't know that I've ever convinced anyone, though…
in reply to Evan

Yeah it's why I tried to use my "modal" example there.

Something that I didn't mention in the article is it's a way of documenting like... how MUCH work went into a commit. Sometimes you have a ~1 line commit that took you all day. A verbose commit is where you can really show your team why that took all day (and it is likely to help someone in the future since tiny changes with huge ramifications should be well-documented!)
in reply to Darius Kazemi

I don't know if I'm going to do any more Git workshops (it's a lot of work), but if I do, I'm going to include this along with the Chris Beams post about formatting
in reply to Darius Kazemi

coworker suggests adding a bit on how to change your default editor! probably a lot of people are scared of being tossed into vi
in reply to alexandra catalina

I think by default it will actually pull up a little picker that lets you pick between vi, nano, and some other ones but... yeah people should have vscode or whatever as an option too haha
in reply to Darius Kazemi

anyway, updated the post with a hyperlink to a how-to on changing the default. thanks for the prod!
in reply to Darius Kazemi

I tend to put those longform descriptions in pull requests, but I see how it could be valuable to have them in the commit message.

When you say ban "-m", surely you mean except for WIP/checkpoint commits that will be rebased/squashed later, right?
in reply to Scott Feeney

yes, correct on -m.

What I like about having this in git is that it stores the important information in git rather than in github dot com
in reply to Darius Kazemi

If you require merge commits, the description of the PR gets copied into the merge commit message. It’s another reason why I personally don’t understand the Rebase/Squash lifestyle: use merge commits and that PR description you put a lot of writing in on github gets nicely copied into your git history.

(Plus then you can use tools like —first-parent with merge commits.)
in reply to Darius Kazemi

Here's the part where I say, "by the way we are hiring a backend engineer with Rails experience and a machine learning engineer" please come work with me and make nice long commit messages:

https://meedan.com/jobs

reshared this

in reply to Darius Kazemi

@Darius Kazemi I'm not a happy person when I'm doing git archeology and come across commit messages just saying "updated" or "fixed bug". Especially if something changed in the code that broke something else and I want to know the implications of changing it back, or further. Information in issue tracking systems tends to get lost, or may be inaccessible over time, or untraceable. (I don't even want to include issue numbers in commit messages, though they are great in merge requests).

I also dislike git -a though...

Now I want to see that programming language that doesn't support multiplication...
in reply to Gidi Kroon

I also dislike -a, I also avoid `git pull` and `git push` without remote/branch identifiers but I don't want to overwhelm people heheh
in reply to Darius Kazemi

and yes, I like keeping as much info in git itself as possible because that way even if you switch issue trackers or git hosting services you still have a very useful history
in reply to Darius Kazemi

very much enjoyed that, and learned about -v which is going to save me keystrokes and focus in the future!
in reply to Darius Kazemi

You probably know this, but you can set commit.verbose true in your config and never have to remember -v again! This is also really useful because you get it mid-interactive-rebase, when it’s a little harder to pass -v manually.
in reply to Darius Kazemi

I'm still laughing at providing multiplication by dividing by the inverse of the operand ...
in reply to CMDR Yojimbosan

thank you I'm very glad at least one person found that as funny as I did 😂
in reply to Darius Kazemi

I generally agree, but I have a caveat to add there

When you feel the urge to write a lot in the commit message, a part of it should probably go into a comment in the code instead, so that the reasoning behind a piece of code is directly accessible there

Description why/how something *is* -> code comment
Why something was changed -> commit message
in reply to Sven "DrMcCoy" Hesse

I've found myself moving away from verbose comments in projects where commits are verbose - the understanding becomes that every line of code has rich metadata you can inspect via git blame etc. Still not sure where I land on the correct distribution of information.
in reply to Darius Kazemi

I see the git history as something that might not always be available. For example, when generating a classic tarball with automake's make dist, the .git directory is usually stripped off

I run Gentoo on my personal machines. I more than once had to investigate why a package suddenly broke compilation on an update (especially when I have set an uncommon set of USE flags). I usually have to dive into the code there and that's usually from a release tarball without git repo
in reply to Darius Kazemi

I agree, but I'm also a stickler for the standard formatting in a git commit.

The first line should be an overview, and be 50 characters or less.

Put as much information as you want in the body, but keep it at the right line limit. I believe it's 72 for the body.
in reply to clacke: inhibited exhausted pixie dream boy 🇸🇪🇭🇰💙💛

I also consider the ticket number absolutely essential and our subject line standard mandates it when applicable (and it should normally be applicable).

The point about punctuation is a good one, and I will ususally commit with a draft message from the CLI and then immediately run git commit --amend to fix it up a bit.

But then I will also most of the time run interactive rebases and fix things up, both code and messages, before pushing things.

I will take this moment to evangelize --rebase-merges which is an absolute godsend and really helps with separating things into focused, topical PR branches.
This entry was edited (1 year ago)
in reply to clacke: inhibited exhausted pixie dream boy 🇸🇪🇭🇰💙💛

We've got some advocates at my work for putting it in the body instead of the subject line, but I do find it essential to have the ticket number available in the short history.
in reply to :flan_reaper:

Yes. If I'm about to deploy to prod, I want to be able to see at a glance in my git lg[0]‌ which features will be included in the deploy and we will put ticket numbers in the release notes too, and in the subject of mails discussing aspects of a feature, etc.

[0]‌ basically a git log --graph --decorate --oneline but with a little bit more candy, see https://gitlab.com/clacke/gists/-/blob/master/.config/git/config#L4
This entry was edited (1 year ago)
in reply to Darius Kazemi

Great stuff! Magit, the Emacs Git client, actually has verbose commit messages as the default which is one way it encourages good practice, it seems.
in reply to Darius Kazemi

Yes. I encourage a # commmit message body format of "Before, …
Now, …
Issue: CMO-123"
#git
in reply to Mark Stosberg

Sounds quite like the C4 format:
Problem: the thingamajigs smurf too much

Solution: transmogrify the flerps
This entry was edited (1 year ago)
in reply to Darius Kazemi

This is why I just don't use the command line. My UI has that second box and it's just begging me to use it....
in reply to Jeff Ward

"UI" huh... I'll have to research what that is...