conflict markers in markdown files

conflict markers in markdown files

[Nicholas Bransby-Williams]

Isn't it quite unfortunate that markdown chose setext-style headers by
“underlining” with equal signs (=) meaning if a header is 7 characters
long it's going to clash with the git conflicts markers (example
below).

Would it make sense to add an option to merge-file so merge tools can
specify a custom marker that is statistically much less likely to
clash with the kinds of text files that are typically stored in git
repositories?

cat ./ours.md
A Second Level Header
---------------------
Ours
=======
Its ours
The quick brown fox jumped over the lazy
dog's back.

cat ./base.md
A Second Level Header
---------------------
The quick brown fox jumped over the lazy
dog's back.

cat ./theirs.md
A Second Level Header
---------------------
Theirs
=======
Its theirs
The quick brown fox jumped over the lazy
dog's back.

git merge-file -p ./ours.md ./base.md ./theirs.md
A Second Level Header
---------------------
<<<<<<< ./ours.md
Ours
=======
Its ours
=======
Theirs
=======
Its theirs
>>>>>>> ./theirs.md
The quick brown fox jumped over the lazy
dog's back.

Re: conflict markers in markdown files

[Philip Oakley]

On 28/10/2021 15:00, Nicholas Bransby-Williams wrote:
> Isn't it quite unfortunate that markdown chose setext-style headers by
> “underlining” with equal signs (=) meaning if a header is 7 characters
> long it's going to clash with the git conflicts markers (example
> below).
>
> Would it make sense to add an option to merge-file so merge tools can
> specify a custom marker that is statistically much less likely to
> clash with the kinds of text files that are typically stored in git
> repositories?
>
> cat ./ours.md
> A Second Level Header
> ---------------------
> Ours
> =======
> Its ours
> The quick brown fox jumped over the lazy
> dog's back.
>
> cat ./base.md
> A Second Level Header
> ---------------------
> The quick brown fox jumped over the lazy
> dog's back.
>
> cat ./theirs.md
> A Second Level Header
> ---------------------
> Theirs
> =======
> Its theirs
> The quick brown fox jumped over the lazy
> dog's back.
>
> git merge-file -p ./ours.md ./base.md ./theirs.md
> A Second Level Header
> ---------------------
> <<<<<<< ./ours.md
> Ours
> =======
> Its ours
> =======
> Theirs
> =======
> Its theirs
>>>>>>>> ./theirs.md

In a similar vein, the above `>>>>>>> ./theirs.md` is being formatted as
repeated side bars in Thunderbird. But that's someone else's problem ;-)

> The quick brown fox jumped over the lazy
> dog's back.

Re: conflict markers in markdown files

[Junio C Hamano]

Nicholas Bransby-Williams <nbransby@gmail.com> writes:

> Would it make sense to add an option to merge-file so merge tools can
> specify a custom marker that is statistically much less likely to
> clash with the kinds of text files that are typically stored in git
> repositories?

Is the conflict-marker-size attribute sufficient?  If not, why?

In our documentation, we do need to have literal runs of '<<<',
'===', etc. to illustrate and describe the conflict markers, so we
have these in .gitattributes at the top-level:

    /Documentation/git-merge.txt conflict-marker-size=32
    /Documentation/gitk.txt conflict-marker-size=32
    /Documentation/user-manual.txt conflict-marker-size=32

so that the auto-inserted conflict markers will be very long,
instead of just the default (was it 7?  I do not remember offhand
because I do not have to).  Most importantly, these "32" are written
by folks who wrote these documentation pages and *knew* that there
is no runs of '<', '=', '|' or '>' that are 32 letters long, so it
is safe and can be updated to stay safe when the documentation files
change.

Re: conflict markers in markdown files

[Nicholas Bransby-Williams]

I guess using such a long marker makes it less likely but there no
reason you wouldn't have a 32 character long title in markdown

Example.... :)

An important heading in markdown
================================


On Thu, 28 Oct 2021 at 20:55, Junio C Hamano <gitster@pobox.com> wrote:
>
> Nicholas Bransby-Williams <nbransby@gmail.com> writes:
>
> > Would it make sense to add an option to merge-file so merge tools can
> > specify a custom marker that is statistically much less likely to
> > clash with the kinds of text files that are typically stored in git
> > repositories?
>
> Is the conflict-marker-size attribute sufficient?  If not, why?
>
> In our documentation, we do need to have literal runs of '<<<',
> '===', etc. to illustrate and describe the conflict markers, so we
> have these in .gitattributes at the top-level:
>
>     /Documentation/git-merge.txt conflict-marker-size=32
>     /Documentation/gitk.txt conflict-marker-size=32
>     /Documentation/user-manual.txt conflict-marker-size=32
>
> so that the auto-inserted conflict markers will be very long,
> instead of just the default (was it 7?  I do not remember offhand
> because I do not have to).  Most importantly, these "32" are written
> by folks who wrote these documentation pages and *knew* that there
> is no runs of '<', '=', '|' or '>' that are 32 letters long, so it
> is safe and can be updated to stay safe when the documentation files
> change.

Re: conflict markers in markdown files

[Junio C Hamano]

Nicholas Bransby-Williams <nbransby@gmail.com> writes:

> I guess using such a long marker makes it less likely but there no
> reason you wouldn't have a 32 character long title in markdown
>
> Example.... :)
>
> An important heading in markdown
> ================================

You probably missed the part that I said .gitattributes is under
control of those who are editing the files the entry refers to.  So
when you edit the file and add such a line, you can easily edit the
attributes file and pick an appropriate number.

Re: conflict markers in markdown files

[Nicholas Bransby-Williams]

Thanks, I didn't miss that.

I have no control over the content in the file so I don't know what an
appropriate number is.

Although I guess an unfeasible large one would make a clash highly unlikely.

On Thu, 28 Oct 2021 at 23:28, Junio C Hamano <gitster@pobox.com> wrote:
>
> Nicholas Bransby-Williams <nbransby@gmail.com> writes:
>
> > I guess using such a long marker makes it less likely but there no
> > reason you wouldn't have a 32 character long title in markdown
> >
> > Example.... :)
> >
> > An important heading in markdown
> > ================================
>
> You probably missed the part that I said .gitattributes is under
> control of those who are editing the files the entry refers to.  So
> when you edit the file and add such a line, you can easily edit the
> attributes file and pick an appropriate number.

Re: conflict markers in markdown files

[Junio C Hamano]

Nicholas Bransby-Williams <nbransby@gmail.com> writes:

> Thanks, I didn't miss that.
>
> I have no control over the content in the file so I don't know what an
> appropriate number is.

Those who are editing the file would be able to adjust the
attributes themselves, no?

RE: conflict markers in markdown files

[rsbecker]

> -----Original Message-----
> From: Junio C Hamano <gitster@pobox.com>
On October 28, 2021 7:11 PM, 
> To: Nicholas Bransby-Williams <nbransby@gmail.com>
> Cc: git@vger.kernel.org
> Subject: Re: conflict markers in markdown files
> 
> Nicholas Bransby-Williams <nbransby@gmail.com> writes:
> 
> > Thanks, I didn't miss that.
> >
> > I have no control over the content in the file so I don't know what an
> > appropriate number is.
> 
> Those who are editing the file would be able to adjust the attributes
themselves,
> no?

It sounds like we might need an attribute like:

*.md	conflict-marker-size=32,conflict-marker-separator='~'

to stick 32 ~ characters as a separator, if going down that path. I'm not
sure how hard this would be, but tooling other systems, like JGit and every
client on the planet would be painful.

-Randall

Re: conflict markers in markdown files

[Junio C Hamano]

<rsbecker@nexbridge.com> writes:

> It sounds like we might need an attribute like:
>
> *.md	conflict-marker-size=32,conflict-marker-separator='~'
>
> to stick 32 ~ characters as a separator, if going down that path. I'm not
> sure how hard this would be, but tooling other systems, like JGit and every
> client on the planet would be painful.

Well, the underline-style markdown headers can use tilde for headers
below the level that uses hyphens, so you'd need to pick a different
separator letter ;-).  I agree that third-party application would
have trouble with an arbitrary setting of the marker appearance
(note that our own "rerere" knows about the attribute).