Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What a good commit message looks like (2011)

github.com

Post reply on HN
Print view View original

81–90 of 100 posts

Re: What a good commit message looks like (2011)

#81

Post by makecheck »

mojuba wrote: post #14

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

The commit message is frequently the only comment that ties the set of changes together so it is a good place to describe the change as a whole. This is not always clear when looking at any particular function, for example.

Re: What a good commit message looks like (2011)

#82

Post by groovy2shoes »

aninhumer wrote: post #61
masklinn wrote: post #56

Earlier quoted context omitted.

> I'm not sure why this matters much? Because wrapped code is generally nonsensical. > If the code doesn't fit on the screen you're viewing it on, then it's not going to be convenient to read Inconvenient is one thing, nonsensical is an other. > When would you have an indented line that shouldn't be wrap-indented? That's noted right after, in the parens: list items. This is not correct wrapping for a list item: * thi…

>Because wrapped code is generally nonsensical. Not really? It's probably slightly more awkward to read than scrolling, but then, the solution is to read code on an appropriately sized screen in the first place. And incidentally, truncated code definitely is nonsensical. >List items. They can be handled as you mention, but it's hardly the worst thing in the world if they're not. And if you really care about formattin…

The word "generally" here has a precise meaning when used in a formal (mathematical) sense. Using that meaning, the phrase "wrapped code is generally nonsensical" could be read as "there exists some code that is nonsensical when line-wrapped" or "the amount of code that is nonsensical when line-wrapped is non-zero". More precisely, it means that, in general, you cannot rely on any ol' code to remain sensical after wrapping has taken place. Hopefully, it's obvious that this is true.

Re: What a good commit message looks like (2011)

#83

Post by chris_7 »

masklinn wrote: post #71
chris_7 wrote: post #59

Earlier quoted context omitted.

Markdown renderers seem perfectly capable of this. git wouldn't even need to disambiguate asterisk for lists vs. asterisk for emphasis.

So every piece of software now needs a markdown renderer?

If Linus wants a consistent commit message format, he should enforce it at the software level, rather than hoping people read a comment he left in a repository about logging his swimming information.

This does not mean that the format needs to be Markdown (which includes embedded HTML, so obviously not Markdown), or that all software needs a Markdown renderer. I'm not sure why you'd conclude that.

Re: What a good commit message looks like (2011)

#84

Post by chris_7 »

falcolas wrote: post #67
chris_7 wrote: post #62

Earlier quoted context omitted.

Is there not precedent for handling that correctly in a plain text field?

Which, in the case of HN and other pages, can either break the formatting of the entire page by pushing the right margin beyond the window, or artificially constrained windows which you need to scroll sideways on. Text layout is a hard problem. It's why TEX (and its derivatives) is still so damned useful (and complicated).

It's really not that hard in this case.

Don't wrap lines with a four-space prefix (or whatever format is decided), wrap lines without one. Allow users to disable the wrapping if they prefer wrapped code. The prefix can be stripped at display time if you wish, so that code is left-aligned - actually, since the formatting isn't encoded in the log, only the semantics, users can configure the display as they please.

Possible handle lines beginning with - as lists and indent them correctly. If a message somehow breaks the format, do not accept it. This isn't TeX-level complexity.

Re: What a good commit message looks like (2011)

#85

Post by groovy2shoes »

compsciphd wrote: post #73
gumby wrote: post #39

Earlier quoted context omitted.

m-X auto-fill-mode. You can add this to other modes automatically. I almost always have it on. Added to Emacs in 1977.

auto-fill mode doesn't reflow paragraphs at will, it just inserts a line break when you go over the limit. For instance, if you're editing a document and write a long sentence, that spreads over 3-4 lines. You then take a scalpel to it to make it more concise, so that it fits on a line or 2. Emacs won't reflow it automatically, you can manually get it to reflow (M-q by default), but its not the behaviors you expect f…

Pardon me for piggy-backing on your comment, but the Vim equivalent of Emacs's auto-fill mode is to `:set textwidth=74 wrap linebreak` (where 74 here is the column at which to wrap, and `linebreak` tells Vim to break at some character specified in `breakat`, which is set to a useful default consisting of whitespace and various punctuation). The default behavior is the same as @compsciphd describes for Emacs: it won't reflow automatically during editing, however, the sequence `gqap` in command mode will reflow the current paragraph (`gq` is a command to format text, and it is followed by a motion to specify the text to format: in this case `ap` is the motion for "a paragraph", i.e., the paragraph which currently contains the cursor).

Vim also has an auto-format feature, which can be enabled with `:set formatoptions+=a` and will make paragraph editing behave a bit more like, say, a word processing program, but the Vim help file cautions that formatting long paragraphs or paragraphs with complicated indentation can get slow. I haven't really used the auto-format feature myself, so I can't comment on how slow it actually seems to be in practice.

Re: What a good commit message looks like (2011)

#86

Post by jordansmithnz »

Nice. At an old job, I got a little bored, so I'd spend time crafting wonderful commit messages. Most of them contained puns, some very subtle, some less so.

In regards to commit ethos, I'm not sure I agree with all of the statements made. To me, something simple/concise, that others will understand, but not lacking in key info, is much better than several paragraphs explaining the same thing.

Re: What a good commit message looks like (2011)

#87

Post by Analemma_ »

greenhatman wrote: post #77
gregmac wrote: post #38

Earlier quoted context omitted.

More importantly, the correct way is the way that is currently being used . If the project uses past tense, use it. If you want to change the convention, that's okay too, but everyone has to change. It's exactly the same issue as coding style. If you can look at code or commit messages and figure out who wrote it based purely on style/formatting, you're doing it wrong (or rather: the person using the inconsistent sty…

Tenses in commit messages seem a bit pedantic and inconsequential. It doesn't really affect much. Unlike tabs vs. spaces, where mixing would cause a mess.

Most code formatting issues are pedantic and inconsequential. Never stopped us from fighting to the death about them ;)

Re: What a good commit message looks like (2011)

#88

Post by usea »

petepete wrote: post #48
BurningFrog wrote: post #43

Earlier quoted context omitted.

OPs point remains. It's git's job to tell me its limitations. Not my job to adapt my tools to it. When practical, of course. In this case, git could simply give a "are you sure you want to commit with these long lines?" warning.

Git copes just fine with long commit messages. Providing the rest of your team is happy with it and your tools can display it ok, just do it.

Agreed. My last two jobs had no line length limit on commit messages (or code) and it was great. But culturally, C# developers don't live in an 80-column terminal window, either.

Re: What a good commit message looks like (2011)

#89

Post by Macha »

k__ wrote: post #70
jbattle wrote: post #68

Earlier quoted context omitted.

yep as telo.. said - whatever will inevitably supercede git. In my own work it was VSS > Perforce > svn > git All of those were good choices when they were new, and suboptimal choices when the next better solution came along.

I had the feeling companies would just stick to their thing. Last I worked with used CVS and always talked about switching to SVN, but never did.

We have CVS, SVN, a legacy internal tool for managing git repos and most recently, Bitbucket. And some of these repos go back years. So companies do migrate version control systems.

Re: What a good commit message looks like (2011)

#90

Post by aninhumer »

masklinn wrote: post #78
aninhumer wrote: post #61

Earlier quoted context omitted.

>Because wrapped code is generally nonsensical. Not really? It's probably slightly more awkward to read than scrolling, but then, the solution is to read code on an appropriately sized screen in the first place. And incidentally, truncated code definitely is nonsensical. >List items. They can be handled as you mention, but it's hardly the worst thing in the world if they're not. And if you really care about formattin…

> Not really? Yes really. > but then, the solution is to read code on an appropriately sized screen in the first place. That's not a solution to anything. > And incidentally, truncated code definitely is nonsensical. Truncated code is visibly truncated, not nonsensical garbage right next to actual code. > They can be handled as you mention And the software knows what a list item is… how? > it's hardly the worst thing…

>That's not a solution to anything.

I'm not sure what scenario you're imagining where you absolutely have to read code in commit messages on an unreasonably narrow screen, and you can't wait until you have an appropriate machine. But if a scenario occurred where that were important, I'm sure you'd manage to read some wrapped code, it's not that hard.

>Truncated code is visibly truncated

Unless it's not, because there's ` + someExtraStuff` just off the end.

>So you're saying git should embed a markdown renderer and text layout engine?

If you really want pristinely formatted commit messages that badly then yes.

Post reply on HN