Skip to content

Git Merge Conflicts

Summary

This article explains how to deal with Git merge conflicts.

TL;DR

Commit Papeeria changes to a temporary-branch, clone the repository using git client and merge papeeria-branch with temporary-branch, commit and push papeeria-branch, sync Papeeria project with papeeria-branch.

It is not trivial

Resolving merge conflicts involves operations with git tools and requires some understanding of merging.

What happens behind the scenes

When you collaborate using a version control system, such as git, your collaborator may modify a piece of text and commit the changes to repository in parallel with your work on the same text in Papeeria interface. Let's call the changes made by your collaborator remote changes while your changes are Papeeria changes. When you run git sync in Papeeria, we pull the remote changes from the repository and try to merge them automatically with the Papeeria changes. In most cases it goes without any issues, however, if remote and Papeeria changes affect the same line of text then you have a conflict which can't be resolved automatically. You have to resolve conflicts manually.

Can you just cancel merge?

If you just ignore merge conflict then your Papeeria project remains the same as it was before you started the sync and you can continue working. However, it is unlikely that you'll be able to sync without conflict in the future, so if you want your changes to get into the git repository, we recommend to resolve the conflict.

Resolving merge conflict in Papeeria

Prerequisites

  • Instructions below assume that you're working on Linux and use command line. If you're using other OS or graphical git client, make sure you know how to match the commands to your environment.
  • You need to be able to run git commands in your terminal.
  • You need to understand the basics of git merge or to be able to use merge tool in your favorite git client.
  • You need to know the remote repository URL (referred hereafter as remote-repo), branch name which is associated with Papeeria project (referred as papeeria-branch) and the last sync point (referred as sync-point). This information is available in the Git section of Version Control pane in Papeeria workspace.

Short overview

When you hit a merge conflict, you need to do three steps:

  1. Commit Papeeria changes to a separate temporary branch. This can be done automatically from Papeeria.
  2. Merge temporary branch into papeeria-branch and resolve merge conflicts. This is the most important step which requires external tools.
  3. Checkout papeeria-branch and pull the merged version into Papeeria project. This can be done automatically from Papeeria.

When you click Start resolving link in the Sync dialog you'll see the wizard which will guide you through the process.

Step 1: commit to a temporary branch

This step is fully automated. Just click Commit button in the wizard to create a new branch (referred hereafter as temp-branch), commit and push it to the remote-repo.

When this step completes, you will be synced with temp-branch and the contents of this branch and Papeeria project will be identical. You need to resolve merge conflicts and return to papeeria-branch as soon as possible, but if you can't do it right now, it is okay to postpone the next steps and just close the wizard. In the latter case we will show you a reminder about the merge conflict in the Version Control pane and you will be able to resume the process by clicking Resume resolving.

Why temp-branch is needed?

If you're git-savvy person then you know that you can merge without creating a new branch. However, we want to let you continue your work and commit Papeeria changes to the repository even in case of merge conflicts. Having completed this step you can just continue typing and postpone resolving merge conflict or ask other user to do the merge for you.

Step 2: resolve merge conflicts

This step requires interaction with command-line or GUI git tools. You need to understand how to deal with merge conflicts. The wizard will show you a sequence of commands which you need to run, and having completed those commands and resolved the conflicts, you'll have a merged version in papeeria-branch. If you're not git-savvy person, you can ask someone else who has access to your repository to do it for you.

When you're done with merging, click I've merged the changes in the wizard. This button actually does nothing but showing you the next step. You can safely close the wizard, open it using reminder link and click the button again.

Step 3: sync with papeeria-branch

When you have merged everything and pushed papeeria-branch to remote-repo, you may want to synchronize Papeeria project with papeeria-branch and continue working on the merged text. This step is automated and you just need to click Checkout button in the wizard.

FAQ

How to avoid conflicts?

If you're not changing the same lines in the same file with your collaborators then you're almost certainly fine.

No conflicts, but my project won't compile after sync!

Yes, it is possible. Merge works with plain text and it doesn't know anything about LaTeX. So if your collaborator, say, deletes a line \usepackage{amsmath} in the document preambule then the remaining part which relies on amsmath is broken, despite that text-wise there were no conflicts. More subtle case: if you have a long enumeration, and your colleague deletes \begin{enumerate} at line X while you add a new \item at line X+100 then the code is broken.

Git hostings such as GitHub usually come with tools for viewing diffs online and even for online merging.

If your git hosting doesn't provide online diffs or if you have your own git server then you may use git tools on your local machine to browse history and view diffs.