For the complete documentation index, see llms.txt. This page is also available as Markdown.

Synchronizing with a Git branch

While it is not possible to synchronize a project directly with a Git branch other than the default branch, indirect synchronization using a local Git clone is possible.

Overleaf users often wish to synchronize their Overleaf project with a specific Git branch, other than than the main branch. Overleaf does not directly support this for either GitHub synchronization or the Git integration.

GitHub synchronization can only be set up against the main branch of the GitHub repository. The Git integration has a similar limitation. However, because Git's refspec allows you to map a local branch to a different remote branch on pushes and pulls, it is possible to work around this limitation.

Why map to a branch?

In Git, branching is often used to work exclusively on a specific version of a project that is kept distinct from the primary version. In most cases, it is expected that the branch will eventually be merged with the main branch.

Researchers often use Git branches for specific asynchronous workflows, such as:

  • Isolated Drafts: Preparing major revisions or response-to-reviewers documents without disturbing the main text.

  • Feature Development: Writing complex code/LaTeX macros or refactoring large tables in isolation.

  • Co-author Reviews: Giving a specific co-author a sandboxed space to make edits before merging into the primary manuscript.

Why is this not supported directly?

Git's asynchronous model that has collaborators working on separate branches is very different from Overleaf's realtime synchronous collaboration model. In Overleaf, all collaborators are working on the same document and changes are automatically reconciled.

The fact that Git's branching model doesn't map on to the history model that is used by Overleaf is one of the key reasons that Git-style branching is not supported directly by Overleaf's GitHub synchronization feature or the Git integration. Recognizing that Overleaf's model is not directly compatible with Git branching, it is still possible to indirectly synchronize with a Git branch, with the understanding that any eventual merging will have to be carried out externally to Overleaf and will not be automatically reflected in the Overleaf history of a particular project.

Synchronizing with a Git branch using the Git integration

In the description that follows, a repository is hosted in GitHub and indirect synchronization with a branch is managed using a local clone that is associated with an Overleaf repository using Overleaf's Git integration. In the examples, is assumed that the branch is test-branch. While GitHub is used in the example, this workflow does not directly use Overleaf's GitHub synchronization feature, and could also be applied to repositories hosted with other providers.

To successfully map a specific local GitHub branch to an Overleaf project, you must

  1. Create a local clone of your GitHub repository;

  2. Configure a second remote on this repository that points to an Overleaf project;

  3. You may need to manually reconcile the differing project histories between the local repository and the Overleaf before establishing a routine synchronization loop.

1

Phase 1: Local setup

First, clone your GitHub repository, switch to your target branch, and link the Overleaf project.

  1. Clone the GitHub repository:

  2. Switch to your specific branch (or create it):

  3. Push the new branch to GitHub (if newly created):

  4. Add the Overleaf project as a second remote:

2

Phase 2: Merging with the Overleaf project

Because the Overleaf project and the GitHub repository were created independently, they have "unrelated histories." You must force Git to merge them locally before you can push. We'd recommend that you start with a simple example project on the Overleaf side, or an empty project. Note: Overleaf does not support git push --force, so it is required to resolve conflicts between the remote Overleaf project and your branch on your local clone, then push back to Overleaf.

  1. Pull from Overleaf allowing unrelated histories:

  2. Resolve Merge Conflicts: Git will likely flag a conflict (e.g., in `main.tex` if both repositories contain one). Open the files, resolve the conflicts to keep your preferred code, and save.

  3. Commit the resolution:

  4. Push the linked history to Overleaf using a refspec that identifies the local and remote branches. This command tells Git to take your local test-branch and push it to the remote main branch expected by Overleaf:

3

Phase 3: Routine synchronization

Once the histories are linked, use the following commands to move work between GitHub, your local machine, and Overleaf.

To pull latest changes from Overleaf:

To push local changes to Overleaf:

To push local changes to GitHub:

Merging your branch

When work on test-branch is complete and you are ready to merge it back into your primary main branch, you have two choices for your Overleaf project[cite: 4]:

Once test-branch is merged into main on GitHub:

  1. Archive or delete the temporary Overleaf project used for test-branch.

  2. Create a new Overleaf project directly from your GitHub main branch.

Option B: Keep existing project

If you want to keep the same Overleaf project active and transition it to track your merged main branch:

  1. Switch to your local main branch:

  2. Merge test-branch into main (or pull the merged PR from GitHub):

    Bash

  3. Realign local main with Overleaf:

  4. Push main to both remotes:

    Bash

Your local main branch, GitHub main, and Overleaf project are now fully unified[cite: 3, 4].

Cautions to keep in mind

It is important to remember:

  • Overleaf is unaware of branching: Overleaf always treats its content as a single, linear line of history. It has no concept of Git branches.

  • Use of Git's refspec is required: You must always explicitly map your local branch to Overleaf's main branch (e.g., git push overleaf test-branch:main).

  • Conflicts with online collaborators: Whenever you are working with the Git integration, edits that happen from others in the web interface will cause new commits to be created when you pull to your local. If co-authors are editing the Overleaf web interface, always use git pull --rebase overleaf main before pushing to avoid rejected pushes or merge conflicts.

Last updated

Was this helpful?