Merging

Because Git was designed around merging code, there are many cases where writing doesn't quite fit with the paradigm of coding. One significant problem are line lengths. Code standards usually have a strong suggestion to keep eighty or 120 columns in length. Writing, on the other hand, can easily exceeds a thousand characters. This means that the tools used to handle merging commits or branches together struggle to show the line.

git diff

diff --git a/src/chapters/chapter-001.md b/src/chapters/chapter-001.md
index 5168898..def5e6f 100644
--- a/src/chapters/chapter-001.md
+++ b/src/chapters/chapter-001.md
@@ -9,7 +9,7 @@ summary: >

 The town of Fires Down Below was an mining town that had risen in the glory of fueling the fires of war before the embers were allowed to darken with peace. A century later, bonfires had been ignited once again in a desperate rush to mine iron deposits needed for the coming battles of magic and machine.

-Beauty couldn't miss signs of the town's resurrection as they rode in from the south. Weathered signs bleached by sun and wind had fresh paint splashed over the faded symbols of old. The new life, however, didn't come with the graceful elegance of the old age. Letters were sloppily forms over neat print and former painted images had been replaced by crude symbols.
+Beauty couldn't miss signs of the town's resurrection as they rode in from the south. The weathered signs had fresh paint splashed over the faded symbols of old. The new life, however, didn't come with the graceful elegance of the old age. Letters were sloppily forms over neat print and former painted images had been replaced by crude symbols.

 There was a sense of fatalism in the air, born by the knowledge that the town would snuff out months after the war ended. Everyone know it and they treated the rising town as a temporary inconvenience in the quest for dominance.

In the above example, it is difficult to see where in the middle paragraph there were changes.

--word-diff

Git has a built-in method for doing word-level differences which make it a lot easier to see word-level differences.

git diff --word-diff

diff --git a/src/chapters/chapter-001.md b/src/chapters/chapter-001.md
index 5168898..def5e6f 100644
--- a/src/chapters/chapter-001.md
+++ b/src/chapters/chapter-001.md
@@ -9,7 +9,7 @@ summary: >

The town of Fires Down Below was an mining town that had risen in the glory of fueling the fires of war before the embers were allowed to darken with peace. A century later, bonfires had been ignited once again in a desperate rush to mine iron deposits needed for the coming battles of magic and machine.

Beauty couldn't miss signs of the town's resurrection as they rode in from the south. [-Weathered-]{+The weathered+} signs[-bleached by sun and wind-] had fresh paint splashed over the faded symbols of old. The new life, however, didn't come with the graceful elegance of the old age. Letters were sloppily forms over neat print and former painted images had been replaced by crude symbols.

There was a sense of fatalism in the air, born by the knowledge that the town would snuff out months after the war ended. Everyone know it and they treated the rising town as a temporary inconvenience in the quest for dominance.

Unfortunately, Git doesn't make it easy to make this a default for a given repository. One approach is to set up a Git alias to use it:

git config alias.wd "diff --word-diff"
git wd

You can't create an alias that matches a command, which is why you can't use alias.diff

[!TIP] The examples here almost never use --global when doing config changes. You can add them if you want, but I need to keep my repositories different and the settings that make sense for writing don't always work for coding.

Alternate Pager

Another approach is to change the pager so it makes it easier to see the differences. One approach is delta. This does a more visual difference but it does highlight the word differences.

git config core.pager delta
git config interactive.diffFilter 'delta'
git config delta.navigate true
git config delta.dark true  # or `delta.light true`, or omit for auto-detection
git config merge.conflictStyle zdiff3

This is harder to put into Markdown, so below is a screen image:

BeyondCompare

I'm a major fan of BeyondCompare. They have have Linux-native versions which are great for code differences but it also does a decent job of working with novels.

git config diff.tool bc
git config difftool.bc.cmd 'bcompare "$LOCAL" "$REMOTE"'
git config difftool.bc.trustExitCode true
git config alias.bc "difftool"
git config alias.bcs "difftool --staged"

As you can see, BeyondCompare can handle line wrapping for differences. It isn't great, but has been a solid tool for me over the years.

Line Formats

Almost everything above this is making the assumption that word-wrapping is done within the program but not in the files. This is known as “soft wrapping”.

Beauty couldn't miss signs of the town's resurrection as they rode in from the south. Weathered signs bleached by sun and wind had fresh paint splashed over the faded symbols of old. The new life, however, didn't come with the graceful elegance of the old age. Letters were sloppily forms over neat print and former painted images had been replaced by crude symbols.

There was a sense of fatalism in the air, born by the knowledge that the town would snuff out months after the war ended. Everyone know it and they treated the rising town as a temporary inconvenience in the quest for dominance.

Another approach, and what is originally described in the original Markdown specification, is to use hard wrapping and formatting the file. This is was Emacs does when you set the fill column to 78 (or your setting of choice).

Beauty couldn't miss signs of the town's resurrection as they rode in from the
south. The weathered signs had fresh paint splashed over the faded symbols of
old. The new life, however, didn't come with the graceful elegance of the old
age. Letters were sloppily forms over neat print and former painted images had
been replaced by crude symbols.

There was a sense of fatalism in the air, born by the knowledge that the town
would snuff out months after the war ended. Everyone know it and they treated
the rising town as a temporary inconvenience in the quest for dominance.

The above example words with Markdown because it takes advantage of Markdown's paragraph break that requires a blank line between paragraphs. It joins each of the consecutive lines with space and uses it to create two HTML paragraphs.

There are two reasons I don't recommend this. One is that the hard-wrapping causes the rest of the paragraph to show differences until the word-wrapping catches up. For example, changing “The weathered” to “Weathered” also shows a difference into the next line.

diff --git a/src/chapters/chapter-001.md b/src/chapters/chapter-001.md
index 49d1fc4..acd232d 100644
--- a/src/chapters/chapter-001.md
+++ b/src/chapters/chapter-001.md
@@ -12,8 +12,8 @@ peace. A century later, bonfires had been ignited once again in a desperate
 rush to mine iron deposits needed for the coming battles of magic and machine.

 Beauty couldn't miss signs of the town's resurrection as they rode in from the
-south. The weathered signs had fresh paint splashed over the faded symbols of
-old. The new life, however, didn't come with the graceful elegance of the old
+south. Weathered signs had fresh paint splashed over faded symbols of old. The
+new life, however, didn't come with the graceful elegance of the old
 age. Letters were sloppily forms over neat print and former painted images had
 been replaced by crude symbols.

Github-Flavored Markdown (GFM)

The second reason is Github-flavored Markdown, also known as GFM. In there, the automatic folding of multiple lines into a single paragraph is altered so the breaks remain. The idea is that in code, putting in a newline is intentional and therefore preserved.

This will be
two lines in Github

The problem is that some websites use GFM and other uses different flavors of Markdown. In those situations, there isn't a way of turning this feature on and off. Because of that, I have a tendency to avoid using newlines in this manner to ensure consistency.

Semantic Breaks

So using hard-wrapping breaks with GFM without a lot of work. However, if that isn't a concern, then another approach for handling lines is to use semantic breaks breaks. This take advantage of the original Fireball specifications, which are also supported by most other common forms. With semantic breaks, you use single breaks with sentences and double newlines for paragraphs.

Beauty couldn't miss signs of the town's resurrection as they rode in from the south.
Weathered signs had fresh paint splashed over faded symbols of old.
The new life, however, didn't come with the graceful elegance of the old age.
Letters were sloppily forms over neat print and former painted images had been replaced by crude symbols.

There was a sense of fatalism in the air, born by the knowledge that the town would snuff out months after the war ended.
Everyone know it and they treated the rising town as a temporary inconvenience in the quest for dominance.

In the above example, each sentence is on a separate line. It still renders as two paragraphs in the end, but the merging is a difference experience.

diff --git a/src/chapters/chapter-001.md b/src/chapters/chapter-001.md
index 3aa15f0..f6441af 100644
--- a/src/chapters/chapter-001.md
+++ b/src/chapters/chapter-001.md
@@ -6,7 +6,7 @@ The town of Fires Down Below was an mining town that had risen in the glory of f
 A century later, bonfires had been ignited once again in a desperate rush to mine iron deposits needed for the coming battles of magic and machine.

 Beauty couldn't miss signs of the town's resurrection as they rode in from the south.
-Weathered signs had fresh paint splashed over faded symbols of old.
+The weathered signs had fresh paint splashed over faded symbols of old.
 The new life, however, didn't come with the graceful elegance of the old age.
 Letters were sloppily forms over neat print and former painted images had been replaced by crude symbols.

I like the idea of semantic breaks, but I found it difficult to integrate into my writing. Too many years of working with paragraphs and muscle memory resists using it. Also, I use prettier in my tools which erases all the semantic breaks.

However, for some authors it may reduce the complexity of merging code and working with Git tools.