 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/ 37 comments
 @BestGirlGrace @darius 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?
@BestGirlGrace @darius 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.
 @darius I'm already a long git commit message writer so this looks like very much my jam!   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.  @darius 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...! @mcc Yeah that is one of the main reasons I avoid -m so that tracks. Cool that mercurial does not share that problem.  @darius coworker suggests adding a bit on how to change your default editor! probably a lot of people are scared of being tossed into vi @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 @catalina anyway, updated the post with a hyperlink to a how-to on changing the default. thanks for the prod!  @darius 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? @graue 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  @darius @graue 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.) 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:  @darius very much enjoyed that, and learned about -v which is going to save me keystrokes and focus in the future!  @darius 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.  @darius I'm still laughing at providing multiplication by dividing by the inverse of the operand ... @darius 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 @DrMcCoy 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. @darius 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 @darius 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. |
Gregory's Server
@darius I can't write a commit any more without using commit -v, it's so good