tags:

views:

69

answers:

2

I like to use markdown notation in my subversion commit messages, planning to one day create a "log" function that will output the commit messages in a HTML page, not unlike Trac's "history" view. (If Trac doesn't have a markdown plugin by then for exactly that purpose.)

Can anybody think of any reasons against this?

The only thing special about this that comes to mind is the use of backticks but they should be escaped like anything else, so that shouldn't be a problem.

+1  A: 

I use trac, which uses Wiki markup for everything (I just checked and it is also used on commit logs). I mainly use * or - for lists, and trac show them correctly.

On next commit I'll see if it accepts backticks (or {{{ and }}}, which is also accepted by Wiki markup), but it most likely will.

I don't see a reason why you shouldn't use Markdown on your own logs, and may be create a small plugin for your Project management and bug/issue tracking system.

voyager
Trac's really nice because commit messages such as "fixes #42" becomes a link to a ticket, "fixes bug introduced in [151]" becomes a link to another changeset.
chelmertz
+2  A: 

Can anybody think of any reasons against this?

Yes: commits should be plain, unadorned text to encourage minimal commit messages. If you need that sort of formatting, your commit messages are not clearly explaining the purpose of the message. In general, commit messages should be short, succinct descriptions of the changes, no more than two or three sentences. If more detail or context is needed, they can reference external issues (e.g. "Fixes issue #184 graphical bug").

If this is not merely a personal preference and your commits actually do require a significant amount of detail and formatting to explain, then they are probably too big and should be broken up into smaller, more easily digested chunks.

John Feminella
I sometimes use lists when fixing related bugs or implementing related features in a single commit.
voyager
Agreed. My source control and bug db are integrated so that I can just refer to cases in my commit messages, and they get auto-linked. I like to give the case# and a quick description. Easy to eyeball in a list and drill down if I need more info.
Lou Franco
@John good points, but I would sometimes like to give a short outline about changes (e.g. `xyz()` now needs the 2nd parameter to be `int`) also with the long-term goal of building changelogs. However, a ticket system may be the better choice for that. Anyway, I like to do some formatting even with conscise log messages, for example `function_names()` or **bold**/*italic* for important things.
Pekka
I think it's okay to delimit phrases that are code accordingly, but anything more is probably where I'd draw the line. For example, I've written commits like "Validates that `this` pointer returns correct reference", because without the backticks it wouldn't be obvious what "this" is referring to.
John Feminella
The great thing about MarkDown is that its "raw" form is still quite readable. So even if you're looking at the Subversion logs "raw" without being processed by MarkDown, it doesn't really get in the way.
Craig McQueen