Using Git and GitHub

Overleaf offers Git-Bridge and GitHub Synchronization features that allow you to link your Overleaf projects with local Git repositories or synchronize them with Git repositories hosted on GitHub. The Git-Bridge and GitHub Synchronization features are premium Overleaf features, available with an Overleaf subscription.

Overleaf Git-Bridge and GitHub Synchronization features allow you to work on your LaTeX source offline, help you to share with collaborators outside of Overleaf, and allow you to integrate Overleaf into more complex workflows.

The Overleaf Git-Bridge

The Git-Bridge is a premium feature. Overleaf premium features are available to participants in Overleaf Commons, members of group subscriptions, and owners of individual subscriptions.

The Git-Bridge feature allows you to clone your Overleaf project to a local repository, treating your Overleaf project as a remote repository that changes can be pushed to and pulled from.

How do I log in to Overleaf through Git?

When you git clone, or perform a git pull from or git push to Overleaf, you will be asked to sign in using your Overleaf user name (your primary email address) and password. Please note that if you signed up using another provider, such as Google or institutional SSO you will need to set an Overleaf password first. You can do this via your Account Settings.

To avoid having to enter your credentials every time, you can configure your git client to remember them, either permanently or for a limited time. There are several options depending on your platform. Please note that SSH key access is not supported on Overleaf.

Please note:

• When providing your primary email address as your login, use lowercase only.
• The colon (:) and at symbol (@) can cause issues for the Git-bridge when used in passwords. If your password currently contains these symbols, you may need to set a new password that does not contain them.

Cloning an Overleaf project as a Git repository

From the Overleaf Project menu within your project, you can select Git from the Synchronization options. This will bring up a dialog showing the git clone command to use when creating your local repository.

Alternately, you can find the Git url from the project url (the url in the browser address bar when you are in a project). If 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

Your Overleaf project will act as a remote repository for your local repository. You can make local changes, commit, and push them to your Overleaf project, and pull updates from Overleaf to your local repository.

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.

1. To start with, we assume that you have git repo on your computer. (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 on Overleaf. You can do this from your My Projects dashboard. You might as well use the 'Blank' template, since we're going to overwrite it.
3. Find the git link for the project. You can find it using the Overleaf Project menu's 'Git' option.

   

4. Add the git link for the project as a remote in your local project.

   $ cd my-paper
   $ git remote add overleaf https://git.overleaf.com/5b98bfbf54474d00010421b1
   

   (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
   

6. Revert the merge to get rid of the files in the existing Overleaf project.

   $ git revert --mainline 1 HEAD
   

7. Push your project to Overleaf.

   $ git push overleaf master
   

8. Visit the project on Overleaf. Your changes will be there. (You may have to open the Project panel to find the new main file.)

Overleaf Git-Bridge Troubleshooting

Please see this page for suggestions on troubleshooting common Git-bridge problems.

Overleaf GitHub Synchronization

GitHub Synchronization is a premium feature. Overleaf premium features are available to participants in Overleaf Commons, members of group subscriptions, and owners of individual subscriptions.

The GitHub Synchronization feature allows you to link your Overleaf projects directly to a GitHub repository that acts as a remote repository for your Overleaf project, and provides a way to push and pull changes between them. GitHub synchronization can only be used on Github.com and cannot be used to connect to other GitHub enterprise installations.

You can synchronize an Overleaf project with a GitHub repository by either creating a new Overleaf project from an existing GitHub repository or by creating a new GitHub repository from an existing Overleaf project. It is not possible to synchronize an existing Overleaf project with an existing Github repository.

Linking your Overleaf Account to your GitHub account

In order to use the GitHub Synchronization feature, you must link your Overleaf account to your Github account. You can do this in your Overleaf Account Settings. Please note that the ability of Overleaf to connect to certain repositories or organizations associated with your account may depend on the permission settings that have been configured in GitHub.

Creating a new Overleaf project from a GitHub repository

From the New Project menu, you can select the GitHub option. This will present you with a list of repositories that are visible to Overleaf through your GitHub account, based on your GitHub permission settings.

Some things to note when creating a new Overleaf project from an existing GitHub repository.

• There are size restrictions applied to Overleaf projects that may prevent larger GitHub repositories from being used to create a project. Please see this page for an overview of limitations applied to the size and number of files in an Overleaf project.

• Overleaf projects do not support Git submodules or Git LFS.

Creating a new GitHub repository from an Overleaf project

From the Overleaf Project menu, you can select GitHub as one of the Synchronization options. This will provide you with a dialog where you can provide the name of a new GitHub repository to synchronize with your Overleaf project.

Synchronizing with GitHub

When you need to push changes to your GitHub repository from Overleaf or pull changes from GitHub into your project, click on the GitHub option in the Project menu.

Known Limitations

Branches: The Overleaf Git system does not support branching.

Symlinks: The 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 over-write the local symlink the next time the project is pulled.

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. When working with GitHub sync, if any files with the execute bit in GitHub are synced to Overleaf, an automatic commit is triggered by Overleaf to reset the file permissions.

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 this commits. In this case we recommend splitting the commit up into two parts, and deleting remaining folder.

Changing GitHub repositories: Once a connection is made with a GitHub repository, a project cannot be directly linked with a different GitHub repository.

Number of files per folder: You cannot have more than 1,000 files in a folder when using GitHub sync.

Track Changes and Comments: Unfortunately, pushes from Git to Overleaf, or pulls of GitHub changes into Overleaf, can cause track changes and comments to become “mangled”; consequently, we do not recommend mixing Git/GitHub and the use of track changes and/or comments. Please contact Overleaf support if you encounter this problem and require assistance—we’ll do our best to help you.