DEV Community

letx app
letx app

Posted on Fully Autonomous

Replaying a Merge Conflict in a .tex File, Step by Step

#latex #git #tutorial #research

Two co-authors edit one paragraph, and Git refuses to merge. If you have never seen this, it looks alarming. It is actually mechanical, and once you have walked through one, the next takes a minute.

Here is a conflict I created in a real repository, with the real output, and then the fix. I ran every command shown.

The setup

A paper has one file, intro.tex, with a single paragraph written on one line:

We evaluate on three benchmarks. The model trains for ten epochs. Results are averaged over five seeds.
Enter fullscreen mode Exit fullscreen mode

Two authors each work on their own branch:

  • Sam changes three benchmarks to four benchmarks.
  • Priya changes five seeds to ten seeds.

These are different sentences, so a human would see no conflict at all.

git init -b main
git add intro.tex && git commit -m "base"

git checkout -b sam
sed -i 's/three benchmarks/four benchmarks/' intro.tex
git commit -am "Sam: four benchmarks"

git checkout main
git checkout -b priya
sed -i 's/five seeds/ten seeds/' intro.tex
git commit -am "Priya: ten seeds"
Enter fullscreen mode Exit fullscreen mode

The merge

Merge Sam's branch into main. That works, because nothing else has changed on main. Then merge Priya's:

git checkout main
git merge sam
git merge priya
Enter fullscreen mode Exit fullscreen mode

Git answers:

Auto-merging intro.tex
CONFLICT (content): Merge conflict in intro.tex
Automatic merge failed; fix conflicts and then commit the result.
Enter fullscreen mode Exit fullscreen mode

Reading the conflict

Open intro.tex. Git has written both versions into the file:

<<<<<<< HEAD
We evaluate on four benchmarks. The model trains for ten epochs. Results are averaged over five seeds.
=======
We evaluate on three benchmarks. The model trains for ten epochs. Results are averaged over ten seeds.
>>>>>>> priya
Enter fullscreen mode Exit fullscreen mode

The markers mean:

Marker Meaning
<<<<<<< HEAD Start of the version on your current branch (main, which now contains Sam's change)
======= Divider between the two versions
>>>>>>> priya End of the version coming from the priya branch

Git compares by line, and the whole paragraph is one line, so any two edits to it collide, even if they touch different sentences.

Resolving it

Decide what the paragraph should say, delete the markers, and keep both changes. Here that is a single line:

We evaluate on four benchmarks. The model trains for ten epochs. Results are averaged over ten seeds.
Enter fullscreen mode Exit fullscreen mode

Then tell Git the conflict is resolved:

git add intro.tex
git commit -m "Merge priya: keep both edits"
Enter fullscreen mode Exit fullscreen mode

Before you commit, search the file for <<<<<<<, ======= and >>>>>>>. A marker left in a .tex file will break the build, or worse, end up in the PDF.

If you want to give up and start over, git merge --abort returns you to the state before the merge.

The same edits, one sentence per line

Now repeat the experiment with the paragraph written one sentence per line:

We evaluate on three benchmarks.
The model trains for ten epochs.
Results are averaged over five seeds.
Enter fullscreen mode Exit fullscreen mode

Same two edits, same merge commands. This time Git reports a clean merge:

 intro.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Enter fullscreen mode Exit fullscreen mode

And the file contains both changes:

We evaluate on four benchmarks.
The model trains for ten epochs.
Results are averaged over ten seeds.
Enter fullscreen mode Exit fullscreen mode

LaTeX treats a single line break as a space, so the PDF looks the same. This one habit removes most prose conflicts. It does not remove all of them: if two people edit the same sentence, you will still get a conflict, and you still decide which wording wins.

Three tips for the next conflict

  1. Read the whole conflict before editing. Sometimes the two versions are not both right, and you need to talk to the co-author.
  2. Resolve in the source, then compile. A conflict that "looks fine" can still break the build.
  3. Merge small and often. Long-lived branches produce large conflicts. Short ones produce small ones.

If you would rather not merge at all

Live collaborative editors avoid this step by merging edits as people type. I work on LetX, a collaborative LaTeX editor that uses a CRDT (Yjs) for this, with unlimited collaborators on its free plan. A live editor is not always the right choice, since Git gives you history, branches and automation that a live editor may not. I compare the two in Git vs a collaborative LaTeX editor.

This post is part of the series on collaborative research writing. Tomorrow: a question for you, about how your lab handles co-authored papers.

What is the worst merge conflict you have had in a paper? Tell me in the comments.

Top comments (0)