Resolving merge conflicts

Summary

What do you need to do when git sync in Papeeria says Merge failed because of conflict.

TL;DR

Commit Papeeria changes to a <temporary-branch>, clone the repository and merge <papeeria-branch> with <temporary-branch> using git tools, commit and push <papeeria-branch>, sync Papeeria project with <papeeria-branch>. See the detailed instructions below.

Be aware that 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. 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.

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
  1. 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.
  2. You need to be able to run git commands in your terminal.
  3. You need to understand the basics of git merge or to be able to use merge tool in your favorite git client.
  4. You need to know the remote repository URL (referred hereafter as <remote-repo>), branch name which your work with in Papeeria (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. Automated
  2. Merge temporary branch into <papeeria-branch> and resolve merge conflicts. Manual
  3. Checkout <papeeria-branch> and pull the merged version into Papeeria project. Automated

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 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.

If you interrupt merging after this step 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.

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 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 button in the wizard.

That's it! We hope the merge went fine.

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 usually come with tools for viewing diffs online. For instance, if you work with branch <papeeria-branch> then you can browse the full history of changes in that branch by pointing your browser to https://github.com/<repository-name>/commits/<papeeria-branch>. Click on a particular commit to see the diffs introduced by that commit.

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.