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.
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
Create a local clone of your GitHub repository;
Configure a second remote on this repository that points to an Overleaf project;
You may need to manually reconcile the differing project histories between the local repository and the Overleaf before establishing a routine synchronization loop.
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.
Pull from Overleaf allowing unrelated histories:
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.
Commit the resolution:
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-branchand push it to the remotemainbranch expected by Overleaf:
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]:
Option A: Fresh project (recommended)
Once test-branch is merged into main on GitHub:
Archive or delete the temporary Overleaf project used for
test-branch.Create a new Overleaf project directly from your GitHub
mainbranch.
Option B: Keep existing project
If you want to keep the same Overleaf project active and transition it to track your merged main branch:
Switch to your local
mainbranch:Merge
test-branchintomain(or pull the merged PR from GitHub):Bash
Realign local
mainwith Overleaf:Push
mainto 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
refspecis 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?