You could add the following style rule to your skin’s CSS:

.timelineModernComment {
    white-space: pre-wrap;
}

Unfortunately, this will also add an empty line above and below every comment, because the generated HTML has a line break between the <span> tag and the comment text, and also between the comment text and the closing </span> tag.

A longstanding wish list item is an option to treat comment text as Markdown, which would give the effect you want. Someone just has to want it badly enough to implement it. It shouldn't actually be all that difficult, since all the pieces are already in place. It's just a matter of stringing them together in the right order.

If you find yourself writing essays in the comment box, you might make use of the new timeline feature to create a wiki article attached to a particular checkin. It's only a few weeks old, so you'll have to build from trunk to get it, for now.

Finally, if you're the sort to run their web browser full-screen, try making it no wider than a book page. Books haven't changed much in size since Gutenberg, for a good reason, yet some people run browsers full-screen on monitors bigger than 12", the widest page you're likely to find. It baffles me. The longer the lines of text, the harder it is to read at a given text size and line spacing.

Unfortunately, these two camps fight, so that many web sites won't render properly with reasonably narrow browser window widths, so you'll have to compromise some.

Thanks for the responses, but I would note that this is not only an issue with viewing the timeline with a web browser, but also with the 'fossil timeline' command. I simply do not understand why the newlines that were present in the editor when doing a commit are not preserved, which seems completely obvious to me. The current approach makes the timeline extremely hard to read (you have to parse the damned thing mentally to find the comments and the fossil transactions they go with) and no, narrowing the web browser doesn't help, because it doesn't restore the missing newlines, and, of course, has nothing whatsoever to do with the output of 'fossil timeline'.

This is such a serious issue for me, because it interferes with my ability to easily view the history of my commits, which is an important part of why you use a version-management system in the first place, that I'm considering returning to git, which does this correctly.

I simply do not understand why the newlines that were present in the editor when doing a commit are not preserved, which seems completely obvious to me.

Well, Fossil has been used by many thousands of people for over a decade, and none of those other people seemed to think this was such an obvious requirement, or if they do, they haven't felt the need to complain about it. Perhaps you have a different perspective.

One approach would be for you to try to understand the viewpoint of the existing developers and users of Fossil and why Fossil works as it does, and then patiently explain why you think preserving newlines in comment display would be a compelling new feature, and how this would help make comments easier to read. Fossil is open-source, so you might even suggest some patches. Perhaps you could do a mock-up of the display as you think it ought to appear, so that we could better understand why your approach is an improvement.

Or, you could continue to tell us all how stupid we are for missing something that is so blindingly obvious, hoping that in our embarrassment, we will rush in and fix it for you.

The first approach is probably what will best move us forward. I invite you to follow it.

I'm a little busy working on SQLite today and do not have time to jump in and a new preserve-newlines feature to the timeline display, at least not right this moment. But if you can make an argument in support of this alternative display style, and flesh-out the requirements a little more, I can perhaps get something going later this week. Or if not me, then perhaps one of the other very capable contributors to the project.

What do you say, Don? Are you willing to work with us on this?

I'm sorry, but your response really seems like a bit of an over-reaction to what I wrote.

I am not accusing you or anyone else of being stupid. I just think the requirement to display the transaction history in an easily-read per-transaction format is clear (paragraphs and sentences serve the same purpose in written language, for example). I don't pretend to know why you chose not to do this in fossil -- you may have had a very good reason that I don't presume to know. But in any case, I don't attribute it to stupidity. I've known a lot of super-smart people in a long career and not one of them was immune to mistakes.

As for making more of a case for this, I really have nothing to add. The readability argument is the key point and I've already made it.

I'm trying to do a quick little hack (maybe a few lines of sed?) to process the output of the timeline command into something resembling what I need. I can't spend a lot of time on this, but if successful, I'll share it and a sample of its output.

As for contributing a patch, just as sqlite imposes demands on your time, I, too, have demands that I can't ignore. So I'm afraid I can't offer any immediate help.

With the BIG caveats that

• what I'm about to say is based on my limited personal experience
• there's a good chance this was a contrived example purely to illustrate the problem, so maybe the substance of your commit messages doesn't actually represent the way you do your work
• in general I agree that preserving newlines in the commit messages makes sense (although I don't believe it is ultimately at all important for the reasons below)

That said. Almost every single one of those sentences in your example would have been expected to be a separate commit at most places I have worked. Consider that the reason this issue hasn't come up before now, and is not obvious for most people, is because it's extremely idiosyncratic to make several unrelated edits in a single commit and want to write detailed descriptions of each of them.

The generally accepted best practice is that, even if several files have changed in a single commit, the changes should be related enough that they can be summarized together in a single sentence of not more than 50–72 characters.

In Fossil, if the change requires more detail then you typically open a ticket in the web UI, keep detailed notes there, and refer to that ticket in the commit message. This is the value of having a full SCM system with integrated ticketing versus Git where you are limited to version control and must rely on extra tools/services for full SCM.

Unrelated edits should always be committed separately. Following this principle will result in a much clearer timeline. This is as obvious to me as the newline-preservation issue is to you.

is because it's extremely idiosyncratic to make several unrelated edits in a single commit and want to write detailed descriptions of each of them.

Ding, ding, ding! Correct answer!

Long commit messages are a sign the checkin is trying to do too much. That makes bisects, code reviews, cherrypicks, backports, and ChangeLog construction more difficult than when each checkin has a single well-focused purpose.

On a good productive day, I can expect to make around a dozen checkins. Occasionally, that'll spike into the multiple dozens.

With short checkin messages, format preservation is less important.

Nevertheless, I do occasionally feel the need to write multi-paragraph comments. This usually happens when I've got a single well-focused checkin where the reason for it is nonintuitive.

I think the most recent time this happened to me, I'd spent a couple of hours working out a one-line fix. I was unwilling to just write "Fixes bug [abcd1234]" in the comment field. I had to explain why it fixes it, which required that I write up what those few hours of debugging turned up.

Perhaps the SVN tradition is different. I dunno. Didn't the OP say he was coming from SVN?

Point them at web sites like the one I linked in my prior post. There's hard-and-fast human factors research behind all of this. Books haven't changed size all that much in 500 years because humans haven't changed all that much in the same time.

Large computer screens are for having at least two vertical windows up side-by-side, each about the width of a piece of office paper, at widest.

No. I ran my Subversion projects the same way, for many years. It's where I learned the practice.

In a public Subversion-based project I ran, I'd frequently get patches posted to the mailing list doing two or more unrelated things, then I'd either have to be a troll and demand the patch be resubmitted, or break it up myself. Since being a troll usually resulted in silence or abuse, I eventually just started breaking patches up and committing the pieces separately without public complaint.

But oh how I grumbled behind my screen. :)

Not that I need to justify the way I work, but I will try to help you understand it. I am retired and working on a personal finance project. I am the sole developer and I therefore I do not need to use the kinds of methods, such as those you suggest, that would be sensible in a workplace (and that I myself required when running software projects) where multiple people are collaborating on a project. So sometimes I include unrelated changes in single commits, because it isn't a problem for me, and you are correct that what I posted is an example of that.

But I do not agree that working the way you suggest reduces the need for preserving formatting. I frequently make related changes to multiple files and commit them immediately, and I think it is essential that the comments and each of the multiple fossil transactions are separated from each other by newlines, just as they appear in the editor during the commit. Again, it's the same readability issue that prompts writer to separate prose into paragraphs.

Even if you went to the extreme of committing changes to files individually, which I don't think makes sense (e.g., makes it difficult to back out a change to multiple files that you discover after the fact has a flaw), I still would want the comments separated visually from the transaction/file description as they appear in the editor buffer during the commit.

So I don't agree with either of you that the need to preserve formatting is as sensitive to the style of interaction with fossil as you think it is.

I would add that preserving the formatting does no harm to those who need or prefer to work as you and wyoung do -- frequent, small commits. So even if you don't think you need it, it does you no harm if you have it. But for those, like me, who can get away with fewer, larger commits, the loss of formatting is a real issue.

Not that I need to justify the way I work

If you want someone else to feel your pain acutely enough to make it their pain and thus choose to solve your problem on their time, then yeah, you do have to justify your work habits, since our work habits clearly haven't caused us enough pain to solve your problem for you already.

if you're unwilling to try to generate sympathy — in its literal meaning — you're reduced to demanding that others work for you for free.

You say presenting the comments the way you expect is "essential," but this push-back you're getting should tell you that we are very far from the essence of the correct approach. We're deep into personal preference territory, which is a good sign that the solution either doesn't belong in Fossil core or it needs to be optional.

I frequently make related changes to multiple files and commit them immediately, and I think it is essential that the comments and each of the multiple fossil transactions are separated from each other by newlines

A cohesive change shouldn't take multiple paragraphs to describe, most of the time, regardless of whether it touches multiple files or not.

Checkin comments should be at a higher level than the code they describe, so as a rule, the description should be shorter than the code. Otherwise, you're probably just paraphrasing the code.

The exceptions are those rare cases where the checkin is highly non-obvious. And there, I usually prefer to put the explanation in a code comment rather than a commit message, which you can format as you like.

the loss of formatting is a real issue.

So add the CSS customization that's been mentioned twice now.

If that doesn't work for you, you'll at least have something to point at to say why it doesn't work.

Here are my requirements for commit messages:

• 1st field - memorable commit identifier (like versions instead of hashes)
• 2nd field - commit title
• 3rd field - commit category (like addition/removal/change/fix)
• 4th field - commit comment with basic formatting (Markdown is readable in plain-text mode, so new-lines are enough) and line/post/character accurate linking to the wiki/forum/diff

Example commit comment:

Description of commit, reason behind the changes.
Explanation why it was merged from this branch instead of that branch.

List of changes:
- better
- faster
- more secure
- [changed to LibreSSL][@@ foo.bar 48,49-67#10-11,71,117-150 | @@ wiki:libressl#18]
- [made it compatible with LibreSSL][@@ goo.bar 8#7,10-49 | @@ wiki:dependencies]

Accurate linking would be for 3-way (2-way +1 comment) diffing.

I hope you will find this post useful for future development. :)

You use the word "demand". I defy you to find that word in any of my posts. fossil is an open source project, made available through the goodness of the developers' hearts. I'm trying to convince them that this is a design mistake they should fix. If they do, they do, If they don't, they don't. I can go back to git, which does this right, in my opinion, or I can fix it after-the-fact with sed. But, I repeat, for your benefit, I am demanding nothing from anybody.

"A cohesive change shouldn't take multiple paragraphs to describe, ...". Did you read my posts? Not clear that you did. I am arguing that per-transaction comments should be separated from the description of the transaction and that the transactions should be separated from each other, exactly as they are in editor buffers during commit. This has nothing to do with lengthy tomes. Useful information is being thrown on the floor between commit time and timeline time. I think that should not be the case.

As for the CSS fix -- does it fix the format of 'fossil timeline'?

... or I can fix it after-the-fact with sed

Just out of curiosity, how can you fix it using sed, when the output of "fossil timeline" strip the original newline from the commit message.

Are you planning to parse the output of "fossil sql ..." to get the original commit message ?

Irrelevant of any particular developers opinions, I believe the sought after effect can be found by appending the (undocumented?) 'comfmtflags' parameter to the timeline command (using any other value then '1' to use the "new" comment format function). Applicable values [for the parameter] can be found examining the file 'src/comformat.c' respectfully.

e.g.

## fossil timeline -comfmtflags 0

... but also with the 'fossil timeline' command.

While looking at the CLI timeline code, I found an undocumented option that might do the job: The "-comfmtflags" option give some control on how the comment are displayed.

To keep the newline, the COMMENT_PRINT_ORIG_BREAK (0x10) flag should do what you want.

Just try it like this:

    fossil timeline -comfmtflags 0x10

Description in the source code:

• https://fossil-scm.org/fossil/artifact?udc=1&ln=464-467&name=e97f8902b57cbce6

If this flag does what you want, it would be easy to add a simple command line option to the timeline command.

EDIT: Actually, thanks to the anonymous simulaneous post on this thread, using COMMENT_PRINT_NONE (0x0) or COMMENT_PRINT_LEGACY (0x1) gave same result for the few test I made.

Actually, when given on the command line, the flags should be in decimal rather that hexadecimal. It also seems like COMMENT_PRINT_WORD_BREAK works better, so the command would be:

    fossil timeline -comfmtflags 8

You can also try with 16 or 24 and see what suits you better.

As a remark, passing any "0x.." to the underlying atoi() would pass on 0 as flags, which results in COMMENT_PRINT_NONE and is seemingly similar to COMMENT_PRINT_ORIG_BREAK.

While we are at it, it would be nice to have a setting for this, e.g. comment-format.

as far as I can see, '-comfmtflags' is really not documented. I think this should be fixed, it might be useful for some people to know about it (personally, I was not aware of it at all, but probably have no real use for it either).

another thought: accepting that the flag makes sense and might get more usage (and yes: a setting controling the default would also be good to have), maybe one should change the name to something more compact (maybe even provide a one letter short option, too).

Actually, when given on the command line, the flags should be in decimal rather that hexadecimal

Yeah, my bad. That's explains why I didn't see any difference between 0x0, 0x1 and 0x10.

I normally use strtoul(...) with base param set to 0 to detect the radix automatically. I didn't realize atoi(...) was used here.

We're deep into personal preference territory,

I disagree. Preserving data is what a DVCS is supposed to do. This includes preserving the commit log.

Fossil preserves the input faithfully, it just doesn't render it how the OP would prefer it to be rendered. As proof that it faithfully stores the data as-is, try:

fossil artifact COMMIT-ID | grep '^C '

The result will be a "fossilized" copy of that checkin's commit message, with spaces represented by \s and newlines by \n (those escape constructs are part of the "fossilized" encoding format). That's exactly what the user enters for the commit message except that leading and trailing spaces might (i don't recall for certain) be stripped.

So, indeed, we're in "personal preference territory" - how to render what the user entered and fossil faithfully recorded. As Richard mentioned, in 11 years of fossil, nobody's been annoyed enough by the existing behaviour to change it (other than console-side wrapping and space-collapsing).

I do not think this is "personal preference" at all, FWIW.

The UI, be it command-line or web, should allow to see the commit message "verbatim" in one way or another. And all this talk about whether messages should be paragraph(s) or 1-liner are completely off-topic IMHO.

The fact such a request comes only after 11 years does amaze me as well.

But I'm not sure at all it paints the OP's request in a bad light, or suggests it is somehow an "esoteric" or "unusual" feature, but rather suggests to me Fossil remains a very niche tool, not in widespread use. Otherwise this would have been requested long ago IMHO.

The fact such a request comes only after 11 years does amaze me as well.

Actually, there was some request before on the old mailing list.

Example:

• Wed, 16 Apr 2014 02:07:35 -0700

• Thu, 26 Nov 2015 04:48:10 -0800

• Mon, 18 Dec 2017 08:18:06 -0800

I guess it never been a very high priority.

It is wonderful that the -comfmtflags flag has been found. I understand that it affects the output of the commit message.

Somewhere above 'anonymous' found that on the input side there is the "--mimetype MIMETYPE mimetype of check-in comment" flag for 'fossil commit'.

What is this mimetype for? How does this affect the potential display?

It would also be great if one could save the desired '-comfmtflags' as per-repository setting.

as far as I can see, '-comfmtflags' is really not documented.

It's documented here:

Environment Variables and Global Options

By the way, this is a very handy document, with a lot of other useful information.

Trying to patch (against [8cb1b231], see below) the code to provide a comment-format configuration option and makes use of it for the timeline command, I've discovered a small problem with the flags: g.comFmtFlags is filled upon parsing commmand line arguments, that is, before opening any repository (according to a comment, probably to ensure that all global flag fields are initialized) and having the chance to read configuration options. That leaves us two options (I chose the second one):

• open the repository directly in main(), read the option, then possibly close it, which seems momentarily overkill but has the advantage of allowing to read the option in one place and use it then in several
• read the comment-format option in every function that makes use of the comment formatting flags

Can someone with a deeper knowledge of fossil's code (drh?) tell us which approach is better?

Index: src/db.c
==================================================================
--- src/db.c
+++ src/db.c
@@ -0,0 +3111,4 @@
+/*
+** SETTING: comment-format       width=16 default=1
+** Sets comfmtflags, the comment formatting flags
+*/

Index: src/timeline.c
==================================================================
--- src/timeline.c
+++ src/timeline.c
@@ -0,0 +2582,1 @@
+  g.comFmtFlags = db_get_int("comment-format", COMMENT_PRINT_DEFAULT);

And, my 2 cents:

In Fossil, command-line options usually allow overriding per-repository settings.

So fossil_get_fmt_flags() should only query the repository database config table if the setting was not yet initialized through the command-line option.

There's also:

fossil help --options

Summarize command-line options common to all commands.

Thanks for the change, Richard. I was just going to submit my patch but still wondering whether it is better to read the option once, so you beat me to it. :-)