I've created a working draft for web UI diffs with word-wrap enabled.

• Commit branch: https://fossil-scm.org/home/timeline?r=diff-word-wrap
• Screenshot 1: https://i.imgur.com/LX15Ubs.png
• Screenshot 2: https://i.imgur.com/63oCnOa.png

No more scrolling required, not even for the side-by-side diffs generated by fossil diff --browser.

The diff text is directly inside <td>, and no longer wrapped by <pre>. Maybe <code> would be more appropriate for single lines, but it seems to have some quirky padding, by default (likely solvable by CSS).

It seemed the "color gaps" problem for increased line-heights can be solved by setting display: inline-block for <ins> and <del>. However, a lone <ins> or <del> that gets wrapped will then expand to the full table cell of its line. This probably isn't too distracting.

I haven't investigated how to keep line numbers (and diff marks) off of text selections, something like this might work:

::before { content:attr(data-line-number); }

Not sure if it's important enough. A far better solution would be to enable per-column text selections for the diff tables, if browsers somehow support this.

Let me know if this is something that could go into Fossil. If yes, I'm ready to implement change requests, fix bugs and address the TODOs noted on the branch wiki page.

(Yet I may be somewhat busy during the next 2 weeks ...)

It's even more a problem with Markdown files where paragraphs are all on a single line.

(And if you're wondering why that's a good idea in the first place relative to using soft line breaks to wrap it at ~72-80 characters as is the common rule in C source code, it's because I don't want the whole paragraph to reflow merely because I added a word near the beginning, creating a lot of pointless noise in the diff. The rule we obey in Fossil's docs to avoid this is to allow line lengths to get very ragged before doing a manual rewrap on them, marking the whole paragraph as "changed.")

I'm not wild about scrolling horizontally, but I do greatly value the ability to see diffs in proper context in cases like this.

Make it a mode if you must, but please don't take the current functionality away.

It's even more a problem with Markdown files where paragraphs are all on a single line.

Isn't this the special case where word-wrapping would be far superior? You'd get a red and green paragraph side-by-side with inserts and deletes marked in more intense red and green, and edits in blue.

Make it a mode if you must, but please don't take the current functionality away.

I'm aware that it's something new that needs time to adopt. And maybe I was a bit overly motivated by Stephan's statement that "wrapping would certainly be a better approach", but the lack of positive feedback from others might have been an indicator that this is not something Fossil users want.

word-wrapping would be far superior

A good number of MD editors give you no choice. If you use hard-wrapped paragraphs in my current favorite, the grammar checker goes mad trying to treat each line separately, yelling about sentences beginning with a lowercase letter and not ending in punctuation, etc.

Such editors word-wrap long lines in the editor, same as a word processor, but they store the paragraphs as a single line. This lets them wrap according to the window width.

If you mean "superior" in terms of the diff results, then no. I find the current diffs far easier to read, particularly when the edits are small. (e.g. Fixing an "a" → "an" grammar error, or fixing commas.)

this is not something Fossil users want.

Some doubtless do, but at the same time, every change breaks someone's workflow. This one happened to hit me and mine.

If you mean "superior" in terms of the diff results, then no.

Just to make sure we mean the same thing when talking about long lines:

You prefer this (with the sync'ed scrolling disabled):

• https://i.imgur.com/gM16cqW.png

Over this:

• https://i.imgur.com/tAl1I3Y.png

Or do I get this wrong?

When I speak of scrolling with single-line paragraphs, I'm not speaking of side-by-side diffs specifically at all. Diffs in this type of document tend to scroll even with maximized browsers on large monitors.

I think I can clarify the use case. Forget my idiosyncratic use of third-party GUI MD editors. Consider instead a Fossil wiki document written in MD format, composed in the browser. You don't hit Enter at the edge of the textarea even though you could, right? You let the browser word-wrap the paragraphs, resulting in very long lines.

Now consider this diff, showing a single-word fix to a document I've been working on recently. It's very clear what I changed to produce the newer document, yes?

Now clone that repo down to your machine and open the same diff under your branch with:

$ ../path/to/diff-word-wrap/fossil ui --page '/wdiff?id=b44c6817eb'

Word-wrapping the diff lines in the browser like this means I have to make comparisons over 3 lines instead of 1 to correlate the location of the change. I would rather grab the mouse and scroll horizontally to localize these changes by direct comparison to the prior version on the line above.

Yes, I do realize my choice means some (or all!) of the diffs may be scrolled off the right edge of the browser. This does not bother me, because Fossil is telling me there is at least one change on this line. I may have to scroll to see it, but I won't overlook it.

... I have to make comparisons over 3 lines instead of 1 to correlate the location of the change. I would rather grab the mouse and scroll horizontally to localize these changes by direct comparison to the prior version on the line above.

Ok, now I see. But, for example, if you have a larger deletion at the beginning of a super-long line, then the next edit's left and right positions on that line may go completely out of sync, and you won't even be able to scroll them both into view horizontally at the same time (in unified diffs).

I think chances are much better that you can see the two related changes at the same time with word-wrap enabled (again, in unified diffs).

But I think it's mainly a matter of taste, and since we've lost the sync'ing, the scrolling (in side-by-side diffs) drives me crazy!

FWIW, for me it felt better with the syncing on. A checkbox will be thoroughly considered 😄

We can re-add that [synchronized side-by-side scrolling] if there's enough interest.

That feature is now back, but in a branch. Whether or not it requires additional changes depends on whether Florian's changes are merged (in which case synchronized scrolling is no longer an issue).

Which only now brings to mind:

@Florian: with your changes, we can revert back to behavior like the current one by simply toggling the word-wrap CSS off, correct? If so, i'd love to see your changes merged, and we can toggle that class via a checkbox (as opposed to generating the diff in the older DOM format). Which reminds me...

We can actually disable selection of pieces of the diff (like the line numbers) using a standard CSS feature:

.prevent-select {
  user-select: none;
}

@Florian: with your changes, we can revert back to behavior like the current one by simply toggling the word-wrap CSS off, correct?

Unfortunately, no.

We can actually disable selection of pieces of the diff (like the line numbers) using a standard CSS feature: ... user-select: none; ...

Yes, that works, and I've just made a change to include only the most recently clicked side of side-by-side diffs for click-and-drag selection. (The feature uses the "pointerdown" event, which seems to come in before the click-and-drag selection starts, which is quite nifty.)

I missed that we removed the syncing. Consider me fighting nail and tooth for that :). The syncing is what made the long lines work!

Why was it removed?

Why was it removed?

It was removed as part of the switch to a CSS grid-based side-by-side diff because its genuine utility is debatable. We still have it in a branch, but whether it will be re-added depends largely on whether the new diff approach described in this thread replaces the current one. Synchronized scrolling won't work with this new approach.

IMO it should at least be an option to keep the old behavior, meaning no word wrap and sync. Everything else would completely break my workflow and I'm guessing for many others as well! The current scrollable and syncing was one of the selling features of Fossil!

... whether the new diff approach ... replaces the current one ...

From the feedback in this thread, I don't think this is a good idea.

Regarding adding word-wrap diffs as an option, I think the following approach is "necessary" (vs. simply toggling a CSS class):

• Add the two word-wrap diff formatters (unified and split) to src/diff.c as new "classes" (the code indeed feels like C++ done in C), i.e. without replacing the current ones. Seems lightweight (it's C).

• Restore the current diff CSS, and add the CSS for the word-wrap diffs as a new block, using unique class names! (I think creating two loaded-on-demand CSS files for scrolling and word-wrap diffs sharing CSS class names won't play well with skinning, and might drive users maintaining their own custom skins mad.)

• Maintain minimal separate code paths for the diff context loader in src/fossil.diff.js.

All in all, this is probably not too much work, and I'm certainly interested in doing it, but likely on a lower priority schedule, in the next time ...

When done, the options / UI / cookies / preprocessor definitions (probably not) required to switch to the word-wrap diffs can be carved out.

Regarding restoring the diff scrolling synchronization JS, I'd recommend to merge that, because there have been votes for the feature independently of the word-wrap diffs? For experimentation and brushing out aches and pains, I'll try to keep the diff-word-wrap branch in a usable state somewhere near the tip of trunk.

I think the following approach is "necessary"...

That sounds like a good plan.

Regarding restoring the diff scrolling synchronization JS, I'd recommend to merge that, because there have been votes for the feature independently of the word-wrap diffs?

Agreed. It's functionally ready to merge but before doing so i would still like to add a checkbox which can toggle that on and off dynamically.

Regarding restoring the diff scrolling synchronization JS, I'd recommend to merge that,

That is now back on trunk, with two differences from before:

• There's a client-persistent toggle for it, defaulting to on. The checkbox to set that toggle appears in these pages: /info, /vinfo, /vdiff, /wikiedit, /fileedit. Where it appears is page-dependent and we can later add it to other pages which may need it by adding a DOM selector for its parent element to an array. The state of the toggle is stored using fossil.storage.set(), which means that it uses localStorage, sessionStorage, or (if those aren't available) dummy transient storage.

• The amount of scrolling for keyboard actions was increased from 25px to 64px.

but in retrospect, I don't think the synchronized scrolling was ever an advantage.

FWIW, that's also my take on it.

I wonder how difficult it would be to make it configurable?

Very little and re-adding that is on my near-term TODO list. We can have a checkbox on the diff page which toggles the behavior without having to force a reload.

And maybe I was a bit overly motivated by Stephan's statement that "wrapping would certainly be a better approach", but the lack of positive feedback from others might have been an indicator that this is not something Fossil users want.

i do agree that wrapping would generally be more legible for me, and i like how github does it, but i also had not considered more use cases than conventional code. On the whole, i'm ambivalent - to me it's a proverbial case of "six one way and half-a-dozen the other."

My only semi-real concern with a table-based layout is the inability to select/copy code, as selecting more than one line will select the line number columns of the following lines. That may not be a real concern, though - we don't often copy/paste from diffs, do we? i do from (diff -tk) quite often when partially-reverting local changes, but don't recall ever having done so from the web UI.

My only semi-real concern with a table-based layout is the inability to select/copy code, as selecting more than one line will select the line number columns of the following lines.

Both GitHub and GitLab can do this. I think line numbers and diff marks are kept off selections by:

::before { content:attr(data-line-number); }
::before { content:attr(data-diff-mark); }

Also column-wise select/copy (i.e. limited to one half of side-by-side diffs; they also use tables) seems possible (at least in Chromium), but I don't know how, at the moment. (Maybe by JS?)

Both GitHub and GitLab can do this. I think line numbers and diff marks are kept off selections by:

Right - github uses (last i checked) CSS counters to do the numbering, and text added via CSS "content" isn't selectable. (Edit: nevermind - as you demonstrate, they now use "data" fields to hold the numbers. Same end effect, though.)

Also column-wise select/copy (i.e. limited to one half of side-by-side diffs; they also use tables) seems possible (at least in Chromium), but I don't know how, at the moment. (Maybe by JS?)

It's very possibly that my recollection is wrong, but my recollection is that attempting to copy (via mouse) text from a table cell, then dragging down, will also copy all columns to the left in subsequent columns. Again, though, that may be incorrect or may be browser-specific.

In any case, i have no strong opinion on the new behavior. i rather like the new wrapping in the examples i've seen, e.g. the up-thread /forumpost/0ad782356d, though.

... copy (via mouse) text from a table cell, then dragging down, will also copy all columns to the left in subsequent columns. Again, though, that may be incorrect or may be browser-specific.

Works for me with FF and Chromium on Windows, even across missing (grayed) blocks in side-by-side diffs. But still no idea how they do it -- what freaks they are!

I'll add a +1 to Warren's comment.

I use Debian Linux on my 3 personal and 2 server machines. I do not have regular access to a Windows machine.

I searched for a suitable Windows text editor for use by remote non-technical associates. After reviewing four different editors, I reverted to a slightly out of date version of Geany. Out of date because the webkitgtk library has not been migrated to 64 bit Windows, so the older 32 bit version is used. I use Geany for almost all my coding work as well as documentation, falling back on nano for editing server configuration files over ssh.

The relevant reason for this choice is Markdown-based prose document creation, translation between spoken languages, and storage in Fossil. For single file documentation almost any text editor will work. For projects with multiple document files, other Geany features are valuable such as keeping a record of all files in the project with easy project switching. It helps to have both syntax highlighting AND a side window showing approximate wysiwyg version of the Markdown file.

Geany also has both automatic hard-wrap and a keyboard command to reflow a paragraph to match the configured line length, both usable during original text creation with automatic reflow disabled during edits. Not all text editors have both.

The Fossil "diff --by" command is appropriate for side-by-side display of changes between repository version and on-disk version of any single file during the edit process, even across multiple files, thus avoiding retention of an on-disk backup copy for comparison outside of Fossil.

During language translation, side-by-side windows in the text editor allow for parallel viewing of one file in the original language and another file in the second language. This is analogous to the Fossil side-by-side diff display and the mental processing is very similar and comfortable.

A related decision that text lines should be hard line terminated at 65 characters is consistent with a founding objective of Markdown that text should be readable and printable without extra processing or line extension to extreme widths (120+ characters) that make eye return to start of next line difficult.

As intended historically, 65 characters fit the width of letter and A4 paper with suitable margins, just like a manual typewriter might produce.

Version differences in one file can be as simple as a single character on a line, which Fossil diffs handle very well for short lines in side-by-side display. Long lines requiring a side scroll are not so handy. And, automatic soft line breaks mislead the reader in not revealing true line content and length.

Warren's "rule we obey in Fossil's docs to avoid noise in the diff" is equally applicable to any prose for which versioning is desirable during creation and revision.

That's my $0.02 or 25 pesos.

Chris

I see no option to turn this off. I like that it is scrollable, because that makes the diff actually usable when there are long lines, e.g. by scrolling the indentation away. This will make it look like on GitHub, which is just terrible and would in my opinion be a huge regression making diffs in Fossil as unusable as in GitHub.

At the very least, this needs to be an option, and I hope an option that is off by default.

... look like on GitHub, which is just terrible and would in my opinion be a huge regression making diffs in Fossil as unusable as in GitHub.

I got it!

At the very least, this needs to be an option, and I hope an option that is off by default.

While this could be done as an option, with separate page-specific CSS and JS modules, I don't like adding even more options to Fossil, and doing the necessary refactoring work and possibly double maintenance exceeds my time reserve and my motivation.

I'm fine with using this for myself, I may do some refinements over time, and if one day the Fossil community would like to have it, maybe they can use my work as a base.

I don't like adding even more options to Fossil

This should be a peer to the existing options in the display cookie, not a wholly new option. The biggest objection I can come up with is that there's limited space on the submenu line; you don't want to make it wrap with reasonable browser widths. (~1000-1200px IMO.)

possibly double maintenance

I've taken a quick look at your patch, and while it does look rather involved, I wonder if most of it can remain unchanged under this option's influence. Isn't handling this a matter of toggling one CSS rule from inline-block to word-wrap?

Isn't handling this a matter of toggling one CSS rule from inline-block to word-wrap?

Unfortunately, no. The generated HTML had to be changed, and consequently the diff context loader.

Ah, you mean take my patch with word-wrap enabled, and then add a toggle option to tweak the CSS to mimic the current (scrolling) behavior.

This would mean to make just one (unified) or two (side-by-side) columns scrollable.

This could work, and I can keep this on my extended TODO list.

The problem is, with the current (non-word-wrapping/scrolling) diff's HTML structure, each diff chunk is encapsulated inside a single <pre> inside a single <td>, so block-wise scrolling by CSS with overflow-x: auto; works.

With new new (word-wrapping) HTML, each line is inside their own <tr>, so when switching the CSS to non-word-wrapping/scrolling mode, multiple <td>s across multiple <tr>s (those belonging to the same diff chunk) would have to scroll synchronously.

At the moment I don't see how this could be achieved in an elegant way.

I think this is nice. I've not reviewed the code yet nor have I built
this branch to test locally so my impression is based on the shared
screenshots, but hope the less than enthusiastic response doesn't
discourage further work.

The majority of my commit and diff reviews take place in the terminal
and the small subset that are done in the browser typically don't
require scrolling as (a) I always view unified diffs and (b) most
projects I work on observe 80 column limits even in markup files.
However, of the subset that are viewed in the browser, the majority are
on the phone or ipad--and this is where wrapping vice scrolling shines.

Thanks to the line number column, wrapped lines are easily distinguished
from normal lines so there's no chance of confusion. Fossil's two-tone
coloured highlights already makes single glyph changes in a line of text
very easy to spot, this is not obscured by wrapping but it is enhanced
by it.

Despite this, it is a novel way to view diffs so I think it should be
optional rather than the default diff format. In any case, nice work,
Florian!

I also think this is nice - especially for mobile devices - and should it be possible to add it as an option, I am all in favour. I appreciate Florian's work and invested time!

... hope the less than enthusiastic response doesn't discourage further work.

Because myself I'm the worst to complain about UI changes, I can understand the feedback! ;-)

As I currently don't see how to implement Warren's suggestion to do a simple CSS-only switch from wrapping to scrolling, my drive (and more so my current spare time) to make the new feature available in parallel to the old is slowed down a bit, because that looks like a bigger (but certainly feasible) undertaking.

And there's still the requirements to keep line numbers and diff marks off of text selections (probably not too hard), and to allow column-wise text selections in side-by-side diffs (no idea how to do this).

And there's still the requirements to keep...

Are those really required, though? They feel like nice-to-haves/bonus points to me. We don't often copy/paste from diffs, do we? When we do so from the CLI we always have to clean up the +/- characters after pasting.

For me, it would also work without these extra features.

The branch wiki page has a link to a stackoverflow.com thread that explains how to implement column selection, and line number and diff mark exclusions could then also be done in the same copy event handler.

But Firefox already has column selection built-in (also see branch wiki page), so in my opinion the additional JS (plus some CSS) to get these extra features could also be avoided.

I’ve followed this thread a bit. I definitely like the idea of word wrapping long lines.

I’ve seen the images and like their look. But I’ve not built a version to try it.

I usually come across this issue during a commit. My script does a diff first so I can see what will happen.

A very long line requiring horizontal scrolling is harder to compare visually since only 80 characters are shown.

Not that it bothers me now, but another UI issue is all the lines scroll horizontally, not just the section clicked in. This would be moot with wrapping.¹

Another UI issue this fixes is when many lines have changed.

When many lines have changed, the horizontal scroll bar is so far down and out of view, one must scroll the page vertically through many lines before finding the horizontal scroll bar. Next, you must slide it horizontally right a bit, then scroll back up vertically to find the comparison line (in which only 80 characters are shown), and go back and forth awkwardly to see the whole line.

I think this would be a great option, and at the risk of upsetting people, I think it should be considered to be the default.

But I should try it out first before sounding so positive. ;-) I was mainly wondering about how to have both this change and what Stephan was working on since they seemed so related, but now his has been merged, I guess that’s not an issue I have to work through. :-)

1. ^{^} Hm, perhaps this changed between the current fossil and the slightly older one I have built on my system. In the browser I use to access the Internet, thus this site, each scrollable area scrolls independently. But in another browser app I use to surf my fossils locally, one horizontal scrollbar moves every scrollable area to the right. This may have to do with Stephan’s recent merge; it could also be due to browser differences. Sorry for not digging that out.

But I should try it out first before sounding so positive. ;-)

My private build of Fossil has quite a few modifications, and I haven't found the time to enable word-wrap diffs for my daily used version, yet.

But even just from dogfooding the diff-word-wrap branch during development, it's clear to me that there's no way back!

I've come to think that word-wrap for diffs has been the "natural" behavior with CLI diff tools for decades, and scrolling diffs are the odd and artificial case.

I need to iron out a few quirks, first, and then find the time to back-fiddle the branch so that word-wrap diffs are optional.

I've come to think that word-wrap for diffs has been the "natural" behavior with CLI diff tools for decades, and scrolling diffs are the odd and artificial case.

Sounds like I agree with you. But I’ve no experience with CLI diff tools in the intervening decades.

Including and predating CRTs, horizontal scrolling past the width of a printout (aka paper) didn’t make sense.

I’m excited.

But I’ve no experience with CLI diff tools in the intervening decades.

Of course, in between CLI tools and web UI, there are GUI diff tools. But as you already mentioned, they have the horizontal scrollbars at the bottom of their window in a fixed location, so there's no need to scroll vertically to find the horizontal scrollbars.

It's also notable that the GitHub and GitLab web UIs default to word-wrap diffs without an option to change that.

I've come to think that word-wrap for diffs has been the "natural" behavior with CLI diff tools for decades

That may be the case on Windows, but the diff command conventionally found on Unix systems truncates side-by-side diffs columns at some fixed width (configurable via a flag).

From my local man diff (GNU diff, though BSD diff is substantially equivalent):

       -y, --side-by-side
              output in two columns

       -W, --width=NUM
              output at most NUM (default 130) print columns

And POSIX diff doesn't specify side-by-side diffs at all :(.

That truncation actually bit me a few days ago when porting some snippets between two files.