> For the complete documentation index, see [llms.txt](https://docs.overleaf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization/synchronizing-with-a-git-branch.md).

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

{% hint style="warning" %}
This page describes a specific scenario for working with Overleaf's [GitHub synchronization](/integrations-and-add-ons/git-integration-and-github-synchronization/github-synchronization.md) and [Git integratio](/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration.md)n features. Please refer to the documentation on those features for general information about them.
{% endhint %}

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.

{% hint style="info" %}
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. 
{% endhint %}

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

{% stepper %}
{% step %}

### Phase 1: Local setup

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

1. Clone the GitHub repository:

   ```bash
   git clone git@github.com:[username]/[repo].git`
   ```
2. Switch to your specific branch (or create it):

   ```bash
   git switch -c test-branch
   ```
3. Push the new branch to GitHub (if newly created):

   ```bash
   git push --set-upstream origin test-branch
   ```
4. Add the Overleaf project as a second remote:

   ```bash
   git remote add overleaf https://git.overleaf.com/[project-id]
   ```

{% endstep %}

{% step %}

### 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:

   ```bash
   git pull overleaf main --allow-unrelated-histories --rebase=false`
   ```
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:

   ```bash
   git add .
   git commit -m 'merged'
   ```
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:

   ```bash
   git push overleaf test-branch:main
   ```

{% endstep %}

{% step %}

### 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:**

```bash
git pull --rebase overleaf main
```

**To push local changes to Overleaf:**

```bash
git push overleaf test-branch:main
```

**To push local changes to GitHub:**

```bash
git push origin test-branch
```

{% endstep %}
{% endstepper %}

## 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:

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:**

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

   Bash

   ```bash
   git pull origin main
   ```
3. Realign local `main` with Overleaf:

   ```bash
   git pull --rebase overleaf main
   ```
4. Push `main` to both remotes:

   Bash

   ```bash
   git push origin main
   git push overleaf main
   ```

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization/synchronizing-with-a-git-branch.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.