TutorialsOverleaf and Git

Overleaf supports integration with Git, which is useful when you want to edit your documents offline and upload your changes later. This tutorial does not explain how Git works in general; it demonstrates only how to get a local copy of an Overleaf project, and when you're done editing, how to upload it back to Overleaf. We tried to imitate an SVN-like workflow here; note that this is not necessarily the most convenient way to work with Git.

This tutorial assumes you're using a Windows system and want to use a GUI. (If you'd rather use a terminal, see here.)

Downloading Git

Before we get started, you'll need to install Git on your system. First download Git itself here and install it. Furthermore download TortoiseGit from here and install it. (In the first-run wizard, make sure you fill out your name and email address; this is how Git identifies you.)

Cloning a project

The goal here is to make a local copy of your project, so you can edit the files offline (make a clone, in Git terminology).

In Overleaf, open the project you want to clone, and click Share (in the header bar). Take note of the Git URL listed below Clone With Git (it should look like https://git.overleaf.com/<...>).
In Explorer, open the folder you want your local copy to reside in. Right-click and pick Git Clone... In the URL field enter the Git URL. By default Overleaf uses some cryptic name; in the Directory field you can change this into a more memorable name, if you want to. Leave all the other settings as they are and click OK.
You'll get a prompt asking for your credentials. For the username, fill out your TU/e mail address. For the password, just use your Overleaf password. When the cloning is done, click Close.

You should now have a local copy of the project.

Updating an existing local copy

Now if someone else makes an edit, and you want to have those changes reflected locally, it isn't necessary to clone the project from scratch. Instead you can just download (pull) the changes into your local copy to bring it up-to-date.

Right-click your copy in the Explorer window, and choose TortoiseGit > Pull... and click OK. Your local copy is now updated with the changes from Overleaf.

Note At this point, you know everything you need in order to use your local copy as a backup. If you also want to make changes locally and push them back to Overleaf, please continue reading.

Make your changes

First, make some (hopefully useful) changes to your paper. We can't help you with that part ;)

After you made a change, you can commit it.

Again right-click your clone in the Explorer window, and pick Git Commit -> "master".... In the resulting dialog, enter a commit message (TortoiseGit enforces this - but see the Tips section below) and select the changes you'd like to commit. Then click Commit.

Note that at this point your change hasn't been uploaded to Overleaf yet; you added the change only to your local clone.

Push the changes back to Overleaf

To upload (push) your commits so others can see your changes, perform the following steps.

First do a pull, to make sure your local copy is fully updated. (Git will prevent you from pushing commits if your local copy is not up-to-date.) If others indeed pushed any commits in the meantime (even to other files), Git will automatically add a merge commit to merge your work with theirs. If Git cannot merge automatically, it will throw a merge conflict that you need to fix manually before you can push (see the next section).
Now, to push your commits back to Overleaf, right-click your copy in the Explorer window, and choose TortoiseGit > Push.... In the resulting dialog leave all settings like they are, and click OK.

The change should be (almost) immediately visible in Overleaf's web interface. Success!

Merge conflicts

If you pull a commit and Git cannot merge it with your local commits (probably because you both edited the same sentence of a file) you have to merge manually.

If a conflict arises, when you close the pull window, TortoiseGit will ask you if you want to see the changes; click Yes. It now shows a list of files that are in conflict.
Double-click a file to display it in the TortoiseGit merge tool. Your version is on the right; the incoming version is on the left.
For each conflict, fix it by right-clicking on the version you want and selecting Use this text block.
Click the Save button and choose Mark as resolved. The file is now removed from the list of files that are in conflict.
When all files are conflict-free, that is, no files are left in the list, click Commit and commit like described above. TortoiseGit will warn you that you are making a merge commit now.
Now you can push like described above.

Tips

If you really want empty commit messages, open the TortoiseGit settings (right-click in Explorer, TortoiseGit > Settings, and open the Dialogs 3 page. Then under Config source select Global and set Minimum number of chars for a commit message to 0 (first uncheck the inherit checkbox).