I work with mercurial, and use long(ish), multi-line commit comments.
Recently, I've put my project on BitBucket.org, and have noticed that when my commit comments are appended to issue pages (see this SO question for information on how/when that happens), the newlines are replaced with spaces, while double-newlines stay double-newlines.
How should I mark single-newlines in commit messages so that BitBucket acknowledges them? I'd like to do this in the least-obtrusive way for when I read the comments normally from the command line.
Break paragraphs (generating <p> tags) with a blank line. Break lines (generating a <br> tag) by ending the first line with two or more spaces, e.g.
Line one␣␣
Line two
Bitbucket formats comments using Markdown, which has this to say about paragraphs and line breaks:
Paragraphs and Line Breaks
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.
The implication of the "one or more consecutive lines of text" rule is that Markdown supports "hard-wrapped" text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s "Convert Line Breaks" option) which translate every line break character in a paragraph into a
<br />tag.When you do want to insert a
<br />break tag using Markdown, you end a line with two or more spaces, then type return.Yes, this takes a tad more effort to create a
<br />, but a simplistic "every line break is a<br />" rule wouldn’t work for Markdown. Markdown’s email-style blockquoting and multi-paragraph list items work best — and look better — when you format them with hard breaks.