> 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.md). # Git integration {% 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 %} For an overview of some other cloning strategies, please see [Advanced Git operations](/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration/advanced-git-operations.md). ### **Overleaf Cloud** If you're using Overleaf Cloud and your Overleaf project URL looks like: ``` https://www.overleaf.com/project/1234567 ``` Then the Git URL to use to clone the project will be: ``` https://git.overleaf.com/1234567 ``` And the command used to clone the project into a local Git repository will be: ``` git clone https://git.overleaf.com/1234567 ``` ### **Overleaf Server Pro (version 4.0 or later)** {% hint style="info" %} Note: The Git-bridge integration is not enabled by default in Server Pro. Please see our [Git Integration](https://github.com/overleaf/overleaf/wiki/Git-Integration) guide for instructions on how to enable it. {% endhint %} If you're using Overleaf Server Pro and your Project URL looks like this: ``` https:///project/1234567 ``` Then the Git URL used when cloning the project will be: ``` https://git@/git/1234567 ``` And the command used to clone the project into a local Git repository using the Git command line will be: ``` git clone git@/git/1234567 ``` {% hint style="info" %} Note: You may be prompted for a password. Please see: [Git integration authentication tokens](/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration/git-integration-authentication-tokens.md) {% endhint %} ## 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. ## Known limitations
BranchesThe Overleaf Git system does not support branching. New clones of an Overleaf project will use main as the branch name (older clones may be using master).
SymlinksThe Overleaf Git system does not handle symlinks. 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 [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 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.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.