# 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 `master`. 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 master branch. ``` $ git checkout master $ git pull overleaf master --allow-unrelated-histories --rebase=false ``` 6. Push your project to Overleaf. ``` $ git push overleaf master --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:master ``` 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.) ## Git commits and the Overleaf Git integration Overleaf has an internal [History system](/writing-and-editing/history-and-versioning.md) that allows simultaneous collaboration within an Overleaf project. This isn't the same as Git, so the Overleaf Git integration is essentially a translation from Overleaf's history and versioning mechanism to Git. This allows many Git-enabled use cases, but it doesn't allow you to work within Overleaf as if it was a complete Git implementation. ### **When are commits created?** When you issue a `pull` or `fetch` command, if no commit exists for the current project state, a new commit is created dynamically. When you `push` files from your local repository to the Overleaf remote, a commit is created at that time as well, which will be visible in any future clones you make of the Overleaf project. When you or others are editing in Overleaf, commits will not be automatically generated until needed. ### **Forcing commits** If you'd like to force a commit to be created at a particular point in Overleaf history, you can do so by [labeling a version](/writing-and-editing/history-and-versioning.md#labeling-a-project-version) in the Overleaf history. The labeled version will get its own commit hash even if you don't do a Git pull right away. A commit will only be created from a label if there have not been any other commits made more recently than the Overleaf history point that is being labeled. ### **Tracking authorship** The just-in-time nature of commits from the Overleaf Git integration means that if there have been multiple changes on the Overleaf side before a commit is generated, the author of the most recent change will be listed as the author of the commit. When working with coauthors, it is helpful to create a label (generating a commit) after each collaborator has completed a significant update—this creates a sequence of commits visible in Git that most closely reflects the changes that are happening in Overleaf. ## 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 %} ## Known limitations
BranchesThe Overleaf Git system does not support branching.
SymlinksThe Overleaf Git system does not handle symlinks well. A symlink can be pushed into an Overleaf project, but will be converted to a regular file, and will overwrite the local symlink the next time the project is pulled.
TagsThe Overleaf Git system does not support tagging.
File permissionsThe Overleaf Git system does not preserve execute permissions. To work around this, you can run git config core.fileMode false in your local clone of the repository. Then you can reset the execute permissions on any affected files. This way they won't be modified again with subsequent Git operations.
Git LFSOverleaf projects do not support Git Large File Storage.
Git submodulesOverleaf projects can act as Git submodules within other repositories, but cannot contain other Git submodules. To reference files from other projects, it is suggested to use the add from another project feature.
Renaming foldersIf a user renames a folder, and pushes the change to Overleaf, the project will retain an empty folder with the old name, in addition to the new folder. (For example, renaming images/ to img/ will leave two folders in the project: img/ containing the image files, and images/, which will be empty. This can cause problems when a user renames a folder, and creates a new file with the same name as the old folder, in one commit. The Overleaf Git system will reject these commits. In this case we recommend splitting the commit up into two parts, and deleting the remaining folder.
Renaming files and moving filesA file rename in your local repository becomes a delete and create on the Overleaf side. This can result in loss of metadata associated with a file on the Overleaf side, causing the deletion of tracked changes and comments. It is not recommended to move or rename files on the Git side that have Overleaf tracked changes or comments.
Track Changes and commentsUnfortunately, pushes from Git to Overleaf can result in the loss or displacement of track changes and comments. Consequently, we do not recommend mixing active use of Git and the use of track changes and/or comments.
## Troubleshooting ### **Repository not found errors** If you are seeing a Repository not found error, it's likely that the wrong URL is being used. The correct URL can be found by clicking the **Git** option inside **Integrations** on the lefthand side within the project. For Overleaf cloud, Git integration is a premium feature, so it will only be available if the project owner has a paid subscription to Overleaf or has been granted access to the feature (by participating in early beta testing, for example). ### **Authentication failed errors** Please see the troubleshooting instructions for [Git integration authentication tokens](/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration/git-integration-authentication-tokens.md). ### **Rate limits** Git Bridge rate limiting does not generally occur when Git operations are executed manually. Some Git clients can be configured to attempt to automatically poll remotes for changes, which can lead to rate limiting errors some cases. Generally disabling any automated polling or reducing the frequency of Git operations should solve these issues. ### **Failure to push references** A failure to push some reference to the remote project can be caused by [exceeding the file size or number limitations of a project](/getting-started/free-and-premium-plans/plan-limits.md) or by including unsupported file types (symlinks, or LFS, for example.) Please review the known limitations listed above to identify any problem files in the commit. In some cases, increasing the postBuffer setting can address failures to push references from your local repository to the Overleaf project. First, you can check your current setting with the command: ```      git config http.postBuffer ``` If there's no output, that means that the default value of 1MB is used. Next, try the command: ```      git config --global http.postBuffer 10485760 ``` which will set the value to 10 MB instead. Now you can try pushing the commit (to either the original project or the new one). If that doesn't work, you can return to your previous setting, or remove the setting with: ```      git config --global --unset http.postBuffer ``` ### **Timeouts** Git commits that include a large number of changes can potentially lead to timeouts. If you encounter a timeout, please try breaking the commit into smaller changes. If the problem persists, consider setting the postBuffer to 10 MB as described above. --- # Agent Instructions: 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: ``` GET https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration/advanced-git-operations.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.