# conflict markers in markdown files 9 messages from 2021-10-28 to 2021-10-29. Participants: Nicholas Bransby-Williams, Philip Oakley, Junio C Hamano, rsbecker@nexbridge.com. Thread: https://gitlist.dev/t/56800 ## Nicholas Bransby-Williams, 2021-10-28 14:00 Subject: conflict markers in markdown files Message-ID: URL: https://gitlist.dev/e/CAGyLXMBWyfcBVFDRbYJMk%2B-RjjNBQDvoDeaBtEPiXpUDDTqfOA%40mail.gmail.com ``` 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. ``` ## Philip Oakley, 2021-10-28 15:38 Subject: Re: conflict markers in markdown files Message-ID: <9561c0de-fb97-093b-4615-6d6d7d595d51@iee.email> URL: https://gitlist.dev/e/9561c0de-fb97-093b-4615-6d6d7d595d51%40iee.email In-Reply-To: ``` 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. ``` ## Junio C Hamano, 2021-10-28 19:54 Subject: Re: conflict markers in markdown files Message-ID: URL: https://gitlist.dev/e/xmqq5ytgrkku.fsf%40gitster.g In-Reply-To: ``` Nicholas Bransby-Williams 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. ``` ## Nicholas Bransby-Williams, 2021-10-28 20:33 Subject: Re: conflict markers in markdown files Message-ID: URL: https://gitlist.dev/e/CAGyLXMA93qQw_h97bMd14O26hSxn4xn%2BAzemVyrf6pn53qO3UQ%40mail.gmail.com In-Reply-To: ``` 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 wrote: > > Nicholas Bransby-Williams 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. ``` ## Junio C Hamano, 2021-10-28 22:28 Subject: Re: conflict markers in markdown files Message-ID: URL: https://gitlist.dev/e/xmqqilxgpywf.fsf%40gitster.g In-Reply-To: ``` Nicholas Bransby-Williams 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. ``` ## Nicholas Bransby-Williams, 2021-10-28 22:49 Subject: Re: conflict markers in markdown files Message-ID: URL: https://gitlist.dev/e/CAGyLXMBe2qj8mT%2BgA2skQr%3D%2BbteV9E0nKZ%3Du-5akCQtTU7AfKA%40mail.gmail.com In-Reply-To: ``` 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 wrote: > > Nicholas Bransby-Williams 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. ``` ## Junio C Hamano, 2021-10-28 23:11 Subject: Re: conflict markers in markdown files Message-ID: URL: https://gitlist.dev/e/xmqqilxgoicq.fsf%40gitster.g In-Reply-To: ``` Nicholas Bransby-Williams 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? ``` ## rsbecker@nexbridge.com, 2021-10-28 23:25 Subject: RE: conflict markers in markdown files Message-ID: <00c601d7cc53$0ce58800$26b09800$@nexbridge.com> URL: https://gitlist.dev/e/00c601d7cc53%240ce58800%2426b09800%24%40nexbridge.com In-Reply-To: ``` > -----Original Message----- > From: Junio C Hamano On October 28, 2021 7:11 PM, > To: Nicholas Bransby-Williams > Cc: git@vger.kernel.org > Subject: Re: conflict markers in markdown files > > Nicholas Bransby-Williams 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 ``` ## Junio C Hamano, 2021-10-29 05:08 Subject: Re: conflict markers in markdown files Message-ID: URL: https://gitlist.dev/e/xmqq5ytgo1u2.fsf%40gitster.g In-Reply-To: <00c601d7cc53$0ce58800$26b09800$@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). ```