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.

Summary

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.

• GitHub Synchronization is enabled by linking your GitHub account to your Overleaf account
• New projects can be created from existing GitHub repositories
• Repositories can be created in GitHub based on existing Overleaf projects
• Linked projects and repositories are kept in sync using the GitHub option in the project's Menu

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

Synchronization between GitHub and Overleaf does not happen automatically, synchronization options are shown by clicking GitHub option in the project's Menu. At that time the GitHub modal will report if there are new changes to pull from GitHub. You will always be presented the option to push changes to GitHub (note: this option will be shown even if Overleaf and GitHub are up to date).

Commits to GitHub are created when the Push Overleaf changes to GitHub button is clicked. At this time an optional commit message can be provided.

• Changes in Overleaf history from GitHub will be shown as being authored by anonymous.

• Changes in GitHub history from Overleaf will be shown as being authored by the connected GitHub account owner.

Resolving merge conflicts

It can happen that when changes are made both in Overleaf and in Github, Git cannot figure out how to automatically merge them. For example, if your collaborator changed a line in Overleaf and you changed the same line in the Github repository, Overleaf may not be able to choose which version to keep.

When that happens, instead of merging into your main branch, we push a new branch to your repository. This branch will have a descriptive name (including the date and time of the branch creation), and contains the version of the document in Overleaf. When you attempt to synchronize with GitHub a message will be displayed that will report that a merge conflict needs to be resolved.

To get back in sync, you need to merge the Overleaf branch into your main (default) branch. You can do this on your computer by pulling both branches and merging with git or any other tool, then pushing the result back to Github. Alternatively, you can do the merge directly on Github by creating a pull request from the Overleaf branch and using their conflict resolution feature. Both approaches are explained in the Github documentation.

Accessing repositories in your GitHub organizations

You can synchronize Overleaf projects with repositories associated with your connected GitHub account, and may also synchronize with projects in GitHub organizations that you are a member of. In order to synchronize with repositories in your associated GitHub organizations, those organizations must grant permission to be accessed by the Overleaf OAuth application.

• If you are an organization member, you can follow the steps described here to request access for the Overleaf app to access your organization.

• If you are the organization owner, you can follow the steps described here to approve the Overleaf app for the organization.

GitHub Synchronization file limits

Overleaf projects are subject to individual size limitations, as well as limits to the total number of files in a project as noted here. While Git itself can handle a single commit changing thousands of files, the GitHub API used by Overleaf's GitHub synchronization feature also imposes limits on the number of files that can be pushed or pulled. It is recommended to limit the number of files in an individual commit to under 100 files, and the overall project size to less than 100 MB if using GitHub syncing. Projects above these sizes may work, but we recommend staying within these limits to avoid potential synchronization issues.

Disconnecting a project from a repository

While it is possible to create multiple projects from a single existing GitHub repository, it is not possible to change the repository associated with a given project. Once a project is linked to a repository, it cannot be unlinked and used to create a new repository. If you need to create a new repository from a particular project, you must make a new copy of the project, and then make the new repository from the copy.

Known Limitations

Branches: The Overleaf Git system does not support branching.

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

File Permissions: The Overleaf Git system does not preserve execute permissions. 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.

Track Changes and Comments: Unfortunately, pulls from GitHub to Overleaf can result in the loss or displacement of track changes and comments; consequently, we do not recommend mixing active work in GitHub and the use of track changes and/or comments.

Direct Synchronization with GitHub Enterprise or GitLab: The GitHub API used by Overleaf can only connect to repositories hosted on github.com. You can indirectly synchronize with projects hosted on other providers using the Overleaf Git integration feature.

Connecting an existing project to an existing repository: It is not possible to synchronize an existing Overleaf project with an existing Github repository.

Authorship of pushes to GitHub: The only Github user that Overleaf is aware of is the user who's GitHub account is linked to the Overleaf account and owns that project. All commits are made using a GitHub API which explicitly makes those commits using that users's identity. So all commits will show in the GitHub Git history as coming from the linked user. In Overleaf's history, changes are shown as "Anonymous (via GitHub)".

Git history and Overleaf history: Changes on the Overleaf side do not have a one-to-one mapping with GitHub commits. Several users can make changes on the Overleaf side, but these changes will be bundled as a single commit under the connected user to GitHub when synchronization is triggered.