> 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/git-integration/advanced-git-operations.md). # Advanced Git operations ## Creating an Overleaf project from an existing Git repository If you have an existing repository, you can add an Overleaf project as a remote repository. There are a few commands below that you'll need to run to get things started. Please note that Overleaf only supports one linear history for each project. The Git integration enforces this limitation by limiting the number of branches to one. That one branch is currently hard-coded to be called `main`. 1. First, we assume you have Git repository on your computer in a folder called `my-paper`. (It might also be hosted on GitHub, GitLab, or Bitbucket, etc., but you need to have it cloned locally, too.) 2. Create [a new project](/getting-started/your-first-project.md) on Overleaf. Since any content in the project will be overwritten, use the **Blank** project option when creating this project and delete the `main.tex` file in Overleaf. 3. Find the Git URL for the project (see [above](#cloning-your-project-as-a-local-repository)). ![](/files/j3i6Tmzz8Y5Mt8hmorsG) 4. Add the Git URL for the project as a remote in your local project. ``` $ cd my-paper $ git remote add overleaf ``` (Be sure to use your own link, not the example link.) 5. Pull the latest content from the Overleaf project and merge it into your main branch. ``` $ git checkout main $ git pull overleaf main --allow-unrelated-histories --rebase=false ``` 6. Push your project to Overleaf. ``` $ git push overleaf main --set-upstream ``` If you want to use a different branch name locally, e.g., `my-branch`, you can push your changes with an alias: ``` $ git push overleaf my-branch:main ``` 7. Visit the project on Overleaf. Your changes should be there. (You may have to open the Overleaf Project menu to find which file has been set as the main document file, and possibly change this initial selection.) ## Synchronizing with another remote Overleaf's Git integration allows your Overleaf project to act as a remote repository for local repositories. However, you may wish to synchronize your Overleaf project with another remote, hosted on GitHub, GitLab, or another Git hosting service. If you're synchronizing your project with a repository hosted on GitHub (), you may wish to use Overleaf's direct [GitHub Synchronization](/integrations-and-add-ons/git-integration-and-github-synchronization/github-synchronization.md) feature. If you are synchronizing your project with GitLab, GitHub Enterprise, or another host, you can use the Overleaf Git integration to set up an intermediary local repository. Following the instructions above for [cloning your project](#cloning-your-project-as-a-local-repository) or [linking a project to an existing repository](#creating-an-overleaf-project-from-an-existing-git-repository), you will have a local repository that can push/pull changes from Overleaf. You can then add a second remote to this repository which points to your hosted repository. Your local will need to have two remotes so that it points to both your Git host and the Overleaf project. Although there will be no direct connection between the Overleaf project and your Git repository, this will allow you to keep them synchronized
## Adding Overleaf projects as Git Submodules Each project on Overleaf acts as an independent Git repository, but if you want to organize several such projects into one Git repo, you can add the repo for each project as a Git submodule in the usual way. You can then push and pull each submodule repository to/from Overleaf individually and still have them collected together as submodules into a larger project. {% hint style="info" %} While Overleaf projects may be submodules within another repository, Overleaf projects themselves cannot contain other submodules. {% endhint %} ## Pulling to and pushing from different branches {% hint style="info" %} Overleaf's Git integration now uses **main** as the branch name. Older cloned repositories may continue to be using the **master** branch name, but all recently cloned repositories use **main**. {% endhint %} Overleaf's Git integration only allows pulling from the **main** branch in the repository that represents your Overleaf project. However, if your local clone is using a different branch name, it is possible to use the Git [**refspec**](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec) conventions (*\*`:`*\*) to name an alternate branch when using `push` and `pull`. ``` % With a local branch "foo" you can pull and push to main on Overleaf git pull foo:main git push foo:main ``` --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration/advanced-git-operations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.