New convention for commit messages on GitHub?


(Dženan Zukić) #21

As I understood, the whole point of limiting the commit summary to 78 characters was for people not having to scroll to see it, and for automatic tools now to word-wrap it. And truncating the last few characters and replacing them with ..., only for those few characters to appear on a line of their own is the opposite of style and readability.

Limit of 78 characters was fine when the commit messages were frequently viewed in 80 column consoles. But now that we have switched to GitHub which imposes 72 character limit, we should consider switching to that limit in ITK commit hook enforcement.


(Matt McCormick) #22

Ideally, no trailing ... for the last remaining characters for all commit summaries with 72 characters or less on GitHub would be nice. But we should consider all constraints. In practice, given the length of ITK class names and experiences writing many commit messages, a hard limit of 72 is difficult to achieve.


(Niels Dekker) #23

A similar discussion item: Should we still manually word wrap the body of commit messages?

Hans (@hjmjohnson) was very kind to merge my pull request 281, even though I did not manually wrap its commit message. He commented that he preferred “manually wrapped at less than 120 characters (prefer 80)”.

I had the impression that with the move from Gerrit to GitHub, manual word wrap of commit messages was no longer needed. Gerrit did not do any automatic wrapping. (I even asked them last year: Automatic word wrapping of long lines in commit text Gerrit Code Review?) Fortunately, GitHub does do automatic word wrapping on the body of a commit message. So I did not see the need to do it manually, anymore. (I don’t really like “hard returns” within a sentence.)

TortoiseGit also smoothly wraps long lines automatically. However, Hans mentioned that git log on the command line is very hard to read with lines >= 120 characters.

So what should we do now?


(Matt McCormick) #24

+1 to @hjmjohnson’s suggestion – Git history is browsed in many ways beyond the GitHub web interface, and wrapping helps in these cases.


(Niels Dekker) #25

Hope you appreciate, with my latest commit, I did wrap manually at 80 characters: https://github.com/InsightSoftwareConsortium/ITK/pull/291/commits/9b398d69d808926539eb752775db30e30e3b8b35 Is 80 characters the right choice, for the body of an ITK commit message?

I feel it’s a bit tedious, though: While I’m writing the commit message, I find myself moving words from one line to another, and counting characters. Doing so distracts me from producing the actual content.

However, looking at those Git Commit Guidelines it seems that the Git community just hasn’t generally embraced automatic word wrapping, in the year 2018. While emeritus professor Donald Knuth already developed his word wrapping algorithm back in 1977, more than 40 years ago!

All I can hope for now is a tool that will automatically add the desired “hard returns” to my commit message, just before the commit takes place. Any suggestion? I find the fix of TortoiseGit issue 1252 - wrap commit logs per git conventions a bit disappointing, as it still does not add those hard returns automatically!


(Pablo Hernandez-Cerdan) #26

Most editors should be able to do the wrapping automatically? I don’t know about others but Vim does it by default in gitcommit filetypes.


(Niels Dekker) #27

Interesting… I’m using TortoiseGit to enter my commit messages, and they decided not to automatically add hard returns, if I understand correctly, from TortoiseGit issue 1252.

So @phcerdan do you never need to manually wrap your commit message? Does Vim just do the right thing for you? Does it never mess up the layout of your text? At how many characters does it wrap?


(Pablo Hernandez-Cerdan) #28

Mostly never, see a gif I prepared for you! I pressed no intro key there, just writing random words, and the new lines are automatic when the line is over 72 characters.

The default is 72, it is what I have, but it can be changed at whatever value the user want. Vim is not doing any extra checking, post-processing or any smart things, just put a new line if the word is over the limit. So, bad style can happen, but it is harder to do it. You can also add a visible column at 72, to see if you are surpassing it.


(Niels Dekker) #29

Hola Pablo!

Thanks for the nice animated gif! I’ve been watching it over and over :smiley:

So what happens when you delete a few words from the middle of an already wrapped line? Does it redo the wrapping for that particular line, as well as the lines that follow?


(Pablo Hernandez-Cerdan) #30

I know, gifs are hypnotizing traps :laughing:

No it doesn’t, it just inserts a new line if the word you are writing is beyond the limit. So, if you are modifying in the middle, you keep writing and then press “gqq” to reformat the line. Or do a visual selection and press gq (like in the following gif):


(Niels Dekker) #31

@phcerdan It doesn’t sound unreasonable, having to explicitly reformat after an edit. Allow me a few more questions, please:

Does Vim also wrap indented text? I hope not, as indentation is typically used for code snippets:

std::copy(imageRange.cbegin(), imageRange.cend(), std::begin(outputImageRange)); // No wrap please!

And does it break long words in two, like HyperrectangularShapedImageNeighborhoodRangeConstIteratorReferenceLikeProxyObject (81 chars)?

What about long URLs, like https://stackoverflow.com/questions/3033423/vim-command-to-restructure-force-text-to-80-columns (95 chars)

I’d be happy with a short answer, but I certainly wouldn’t mind another gif :upside_down_face:


(Pablo Hernandez-Cerdan) #32

Yes, it does wrap it if you are writing it, if you are copying it from elsewhere it doesn’t (see gif). As a note, I would recommend the ticks ``` for marking a code block instead of indentation.

Vim is simple, if you are writing out of your desired limits, it wraps (if it doesn’t break a long word/url). You can revert the wrapping with one keystroke, and vim won’t try to fight. If you reformat the whole file, it will reformat, as asked, no matter if there are indents. But of course you can be selective on what paragraphs you want to format.

Having showed vim, it is probably a little bit of an overkill to learn it for commits. I like it a lot, and recommend it, for me is like a pleasure to use it, not sure if I would be more or less productive with other tools, but I enjoy it a lot. It has a challenging learning curve at the start, but it is worthy! :smile:


(Dženan Zukić) #33

I hate Vim. Ever since I tried using Linux on my own, and had to restart (Ctrl+Alt+Del) to quit Vim, as quitting Vim is neither intuitive nor trivial :angry:

Eventually, I learned how to quit Vim, but that is my main piece of knowledge about it. Hence the continued hate :snake:


(Niels Dekker) #34

I learned how to use vi as part of my study Computer Science, but nowadays I rarely use it, anymore. Still I’m interested to know how Vim supports that feature of automatically adding hard returns. (Even though personally I prefer “soft returns”: just let the line length adapt dynamically to the window size.) Because maybe I should submit a request for TortoiseGit to implement the same feature.


#35

A few other ideas:

SourceTree (http://www.sourcetreeapp.com) There is a setting that will allow you to place a vertical line at any column you chose. I set it at 77 to allow myself a few overflow chars for short words. You still have to add the manual line break but with the bar there it visually works well.

Nano:

export EDITOR=”nano -c”

then when you “git commit -s “ nano will fire up and at the bottom of the screen it will tell you which column you are currently at. Works with “Git Bash” on Windows also.

Again, you will need to place the hard returns in your commit message but at least nano will tell you which column you are in. ctrl-o, enter, ctrl-x, to save and exit.

Maybe someone will write an extension for nano to auto add the hard returns. I bet there is a super slick way to pipe the output of the commit message through a awk/sed/something that would do the auto hard word wrap for us. I agree that adding the hard returns is tedious at best.