In a few of the open source projects I work on at work, we’ve started asking that folks contribute using a specific structure for their commit messages.
Explain here the context, and why you're making that change.
What is the problem you're trying to solve?
Describe the modifications you've done.
After your change, what will change?
It works pretty well for frequent contributors, but it’s just another hurdle for new contributors, which is a little frustrating.
[Comment removed by author]
The bigger issue in my mind is that it seem to imply every commit should be a solution to something, which promotes non-atomicity in commits. It’s quite easy to think of situations where a problem is not solved by a minimally meaningful unit of work. Maybe a problem requires a backend and front end change, it would not seem unreasonable to split that work into two or more commits if they can stand separately, yet together they only solve one issue and individually don’t form a full solution.
Github allows you to submit a description with a pull request, a three part description like this would seem ideal there while a given pull request can still be composed of several smaller commits.
So does your shortlog look like this?
No, there is still a one line summary first. The pattern above is for the remaining message after the initial line.
View the repo in question to see the result.
This is all reasonable, although I dislike the bit about hard-wrapping at 72 columns. The author is 100% dead wrong about the command line interface, however – git’s is terrible, requiring IDE support for even the most trivial of tasks. I’m an old UNIX greybeard (albeit a self-hating one) and every time I have to use the git cli I weep angry tears of blood. Of course, there’s always magit to ease the burden.
I’ve never used an IDE to interface with git. What am I missing?
I use SourceTree, although I’ve heard good things about Tower. One of the main reasons I use it is for staging selected lines and hunks. You can technically do the same with the cli, but it’d take a prohibitive number of commands instead of one click, and even more commands to know if you did it right. Plus, I sometimes start to write a commit message, and then realize that there are files I should add or remove from that commit. That is easy with an IDE, very difficult with the CLI.
Also, always being able to see a visual display of the branches is helpful, and I know when others have pushed to other branches without having to manually check.
for me, diff looks better. Nothing else.
For starters, being able to selectively stage changes in a file. Unless you count git add -p as equivalent.
Hard-wrapping at 72 columns is nice for command-line interfaces like
tig. There’s also some code review tools
that mail git diffs; they are much easier to read with hard-wrapping.
I can see that. But everybody should just be using magit in emacs, which makes the problem go away.
you do realize not everyone is using emacs, right/
Ah, but they should be.
requiring IDE support for even the most trivial of tasks
I don’t think git has any more difficult of a cli for trivial tasks than most other cli tools (where “trivial tasks” are push, pull, merge, rebase, add, commit, etc).
What specific things do you find IDE support necessary / extra helpful for?
Interactive rebasing. Generating patches. Visualizing the commit history, particularly with branches. Shit, even switching to local copies of remote branches is weirdly magic. Perhaps I simply don’t understand it well enough, but it certainly doesn’t seem to have a consistent, orthogonal set of functions that can be usefully composed; it just feels like somebody else’s mental model expressed without intermediation.
I still find it super useful, of course, but that doesn’t mean I think it’s good.
Oh, yeah, I use gitk for visualizing the commit history. I’m reasonably comfortable with interactive rebasing but I’m always afraid I’ll merge a commit with the wrong thing.
What do you mean by “generating patches”? git diff?
Probably git format-patch.
Hmmm. I disagree.
To me, a commit is the wrong granularity for this kind of extended information. Extended information belongs in an issue, which can include rich text, sketches, screenshots, references, discussions, apologies. I believe strongly in “commit early, commit often” especially when multiple developers are working on one issue … to me, that’s the beauty of easy branching & merging. So you end up with a branch for the issue, with a string (dag, really) of commits each of which just has the issue number and a couple of words to identify which part of the process it is.
The commits with the comment “#123 create database model”, “#123 ajax api”, “#123 tests” and “#123 new frontend” can all be easily connected back to issue 123 the contents of which go into why this new thing was needed, how urgent it is why it is O(N3) but that’s okay because N <= 1000, and so on.
Many issues trackers including Github’s builtin one can automate this linkage between commits and issues.
This is very nice, but “If I had more time, I would have written a shorter letter”. Sometimes, you have a fix, and it must go out. The code is fine, but the prose centers of your brain are not working at top level. It’s hard to be concise and articulate. The title is the best you can cobble together at that point, and the body of the commit, well, it could be better. Should you delay the commit?
Unfortunately, editing older, pushed, git commit comments is a little tricky. It probably should be easier.