Git integration

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.

For an overview of some other cloning strategies, please see Advanced Git operations.

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)

Note: The Git-bridge integration is not enabled by default in Server Pro. Please see our Git Integration guide for instructions on how to enable it.

If you're using Overleaf Server Pro and your Project URL looks like this:

https://<SHARELATEX_SITE_URL>/project/1234567

Then the Git URL used when cloning the project will be:

https://git@<SHARELATEX_SITE_URL>/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@<SHARELATEX_SITE_URL>/git/1234567

Note: You may be prompted for a password. Please see: Git integration authentication tokens

Git commits and the Overleaf Git integration

Overleaf has an internal History system 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 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

Branches	The 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).
Symlinks	The 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.
Tags	The Overleaf Git system does not support tagging.
File permissions	The 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 LFS	Overleaf projects do not support Git Large File Storage.
Git submodules	Overleaf 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 folders	If 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 files	A 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 comments	Unfortunately, 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.

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