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.
- 1 The Overleaf Git-Bridge
- 2 Overleaf GitHub Synchronization
- 3 Known Limitations
The Overleaf Git-Bridge
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.
- 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:
Then the Git url to use to clone the project will be
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.
- 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).
- 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.
- Find the git link for the project. You can find it using the Overleaf Project menu's 'Git' option.
- 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.)
- 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
- Revert the merge to get rid of the files in the existing Overleaf project.
$ git revert --mainline 1 HEAD
- Push your project to Overleaf.
$ git push overleaf master
- 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
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.
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.
- Creating a document in Overleaf
- Uploading a project
- Copying a project
- Creating a project from a template
- Using the Overleaf project menu
- Including images in Overleaf
- Exporting your work from Overleaf
- Working offline in Overleaf
- Using Track Changes in Overleaf
- Using bibliographies in Overleaf
- Sharing your work with others
- Using the History feature
- Debugging Compilation timeout errors
- How-to guides
- Guide to Overleaf’s premium features
- Creating your first LaTeX document
- Choosing a LaTeX Compiler
- Paragraphs and new lines
- Bold, italics and underlining
- Mathematical expressions
- Subscripts and superscripts
- Brackets and Parentheses
- Fractions and Binomials
- Aligning equations
- Spacing in math mode
- Integrals, sums and limits
- Display style in math mode
- List of Greek letters and math symbols
- Mathematical fonts
- Using the Symbol Palette in Overleaf
Figures and tables
- Inserting Images
- Positioning Images and Tables
- Lists of Tables and Figures
- Drawing Diagrams Directly in LaTeX
- TikZ package
References and Citations
- Bibliography management with bibtex
- Bibliography management with natbib
- Bibliography management with biblatex
- Bibtex bibliography styles
- Natbib bibliography styles
- Natbib citation styles
- Biblatex bibliography styles
- Biblatex citation styles
- Multilingual typesetting on Overleaf using polyglossia and fontspec
- Multilingual typesetting on Overleaf using babel and fontspec
- International language support
- Quotations and quotation marks
- Sections and chapters
- Table of contents
- Cross referencing sections, equations and floats
- Management in a large project
- Multi-file LaTeX projects
- Lengths in LaTeX
- Headers and footers
- Page numbering
- Paragraph formatting
- Line breaks and blank spaces
- Text alignment
- Page size and margins
- Single sided and double sided documents
- Multiple columns
- Code listing
- Code Highlighting with minted
- Using colours in LaTeX
- Margin notes
- Theorems and proofs
- Chemistry formulae
- Feynman diagrams
- Molecular orbital diagrams
- Chess notation
- Knitting patterns
- CircuiTikz package
- Pgfplots package
- Typesetting exams in LaTeX
- Attribute Value Matrices
- Understanding packages and class files
- List of packages and class files
- Writing your own package
- Writing your own class