Hacker News Reader

Comment by Havoc | Hacker News Reader

Opens the temptation to write essays. One liners forced a certain brevity

I love essays in commit messages! They can be very useful, especially when they describe why the change is being applied, instead of what is being done, which is usually the case.

Many high-profile projects have essays in their commits; I'm familiar with those of Go, e.g. https://github.com/golang/go/commit/5779bb4e92911271583faa13... (picked one at random).

I like to go with a brief "what i've done and why". Maybe "BUG-123 (Broken profile page) - Fixed missing CSS".

Why did the bug happen? How were users affected?

Why was this particular "fix" chosen, instead of perhaps a more obvious alternative? (If I can choose only one thing to improve, it'd be this one! Had I gotten a penny for every head scratching "fix" that seems unnecessarily complicated or not a fix at all...)

What steps have been taken to avoid this in the future? New validations? Have new exceptions been introduced? New log rules? New monitoring rules? And if not, then why not?

Are these corresponding changes in other repos or this one? Is this change part of a larger series of changes?

There's so much more you'd like to know when you stumble on a commit like "fix missing css". Yes, some of this info is probably in the ticket. Yes, there is probably a discussion in the pull request. But likely not, if we are to be honest about it. And if it is, then all the easier to summarize in the commit message.

I'm one of those persons that read more code than I write nowadays, git log -G is my favorite command, and commit messages like the above hurts me daily.

> I'm one of those persons that read more code than I write nowadays, git log -G is my favorite command, and commit messages like the above hurts me daily.

-G just looks for changes in the patch so the commit message would not be relevant save possibly once you've reached an interesting-looking revision, do you mean `--grep`?

I've already made a similar comment elsewhere in this discussion but I really don't get why most of these things is better stored in a commit message than, say, as a comment in the code itself, which will always be here even if I'm just browsing through the code by following a call stack or if the file gets copied into another project for instance.

I don't "git blame" all the code I read all the time, and even if I did one small refactor or variable renaming is enough to make it tricky to track the original change back. Comments are forever.

Comments and commit messages are complementary. The commit message describes the changeset and includes things like the above, the whys and the necessary context to understand the change. The comment describes the actual code as it is, and should describe how it works and how it interfaces with other code. Comments tend to be, as you say, forever while the code changes.

Both are well worth the time to write. Nicely written ones might even take a full minute or two to write, but how many cleaned-up and rebased commits does one produce in a day? A few, at most, unless they are absolutely trivial. Those minutes per workday are well spent.

Both are best! A brief concise first line summary together with a full message.

I'd assumed people only used -m for commits they're planning on discarding later. A single line is rarely descriptive enough for real work.

Brevity is a virtue. Failing to write a descriptive commit message, is not.

If you make lots of small commits, a single line is enough.

I do make lots of awfully small commits, and a single line is rarely enough (but sometimes it indeed is)

I generally disagree. Someone already linked to [0]. The background there is quite involved, and it doesn't go away if you break down the commit into many smaller ones. You could argue that sort of write-up belongs on a task-tracker like Jira rather than in a git commit message, but that's a different question.

Besides, overly small, overly numerous git commit messages are clunky. They clutter the commit graph without adding value, making it harder to get a clear picture of the work history in the repo. There's a happy middle-ground for the size of a commit: it should correspond to a meaningful unit of work, not the smallest committable unit of work. Of course, using too few very large commits is a problem too.

Perhaps, as gspr says, a single-line format may make sense in some instances. If a formalised format is used (as shown in [0]) then of course you'll never have the option.

[0] https://github.com/golang/go/commit/5779bb4e92911271583faa13...

I'd say a message saying just "typos" is fine for a commit that fixes a bunch of quite obvious typos, for example. Or "added accidentally missing files" for one that adds some files that should have been tracked all along. Or "cosmetic" for one that cleans up some extra newlines or something.

You're right, it might make sense for simple changes, in the absence of a standard format for commit messages.

> One liners forced a certain brevity

To the point that they're useless. Single-line commit message means you get at best the outline of the purpose of the commit, which is often fine but as I age I find that properly explaining the why and how, and possibly alternatives which were considered and discarded (and why) are absolutely invaluable.

My "model" for commits is postgresql, many messages are simple matching the commit itself (e.g. fix typo), but a number provide necessary background to the change e.g. https://github.com/postgres/postgres/commit/f3faf35f370f5586... says what it does in the short description, but then spends 4 paragraphs explaining the background of the issue, the change's concept, justification for changes going alongside it, and a link for more extensive discussions in case the rest was not sufficient (which it usually is).

Reply on news.ycombinator.com