How to use Overleaf + Git to manage your TeX file

Overleaf is an online TeX editor with a lot of functionality. Most importantly for me, multiple persons can work on the same file at the same time, so it is ideal for collaboration. However not all people like to write TeX within the browser; many have their own preferred editor (TeXShop for example). Here I'd like to explain how to use your TeX editor to work with Overleaf. Edits made with the method here will be availabe via the ordinary Overleaf interface, so any of your collaborator who prefers to use Overleaf directly can continue to do so. An added bonus is that you have a clear view of all the changes made by every collaborator. For this you need to use something called git.

(The owner of the Overleaf project needs to be a paid member to use this feature. I think Overleaf is worth supporting, so please become a paid member, or ask your senior collaborator to do so.)

"git" is a protocol which allows many people to work on the same project consisting of multiple text-based files. This protocol "git" was developed by Linus Torvalds, the original developer of Linux, so that the many developers of Linux all over the world can work together. TeX is also text-based and git can handle it. There are many advantages:

  1. If multiple persons make off-line changes on different parts of the file, git automatically merges the changes. So, multiple authors can work on different sections of a TeX file at the same time.
  2. If multiple person make different changes on the same line of the file, git notifies you saying that there is a "conflict", and ask you what to do.
  3. Also, who did which changes to the files are all easily visible with git as already shown above, so you don't have to tell your collaborators which part you edited.

Overleaf adopts git, so everything I said applies to overleaf. The basic steps to use git are:

  1. For multiple persons to work on a project with git, first you need to have an on-line "git repository".
  2. Then each person needs to clone the repository, which creates a local off-line copy of it.
  3. You then work on the local files as usual (e.g. use TeXShop for TeX.)
  4. Once you're satisfied with your local change, you commit it to your local repository.
  5. You then push it to the on-line repository.
  6. You can obtain other people's changes by pulling the change from the repository to the local copy. One point to note is that, depending on your editor, you might need to close the file in your editor before pulling the changes. This is because pulling the change modifies the files on the disk directly, and not all editors automatically pick up on-disk changes to an already open file.

"git" is originally a command-line app, but of course there are many graphical user interface for that. Here I will use GitHub Desktop. So please download and install it. On the first launch, it will ask you if you want to create a GitHub account. If you just use it with Overleaf, you don't need to create one, so you can skip this step.

(The relation among git, GitHub, GitHub Desktop is somewhat confusing. git is a general protocol. GitHub is a very popular service which provides online git repositories. GitHub Desktop is a free GUI app created by GitHub which allows you to manipulate git repositories not necessarily hosted on GitHub. Here we're going to use GitHub Desktop simply as a GUI app to manipulate our git repositories, so you don't need any account on GitHub.)

Let us now clone an Overleaf project. For this, you need to open a project in the Overleaf website. Please click the menu icon in the top-left corner:

Then click the button saying "git":

This will show an URL of the form https://git.overleaf.com/XXXXXXXXXX where the part XXXXXXXX depends on the project. Now you open the GitHub Desktop. From its menu, select "Clone a repository". You will then see something like this:

You choose the third tab saying "URL", and paste the URL given by Overleaf into it. You also need to choose the folder to put the TeX files. Now click "clone". This will ask you your Overleaf account and the password, which you need to provide only once.

Now it's basically done. Please open the folder you just selected; you'll find the TeX and associated files. Now you can work on the TeX file. Once you worked on a paragraph or so, you can commit it. To do so, go to the "Changes" tab of GitHub desktop:

Often, there are files you don't have to commit, such as .aux files. For these, you use the context menu to tell git to ignore them. Then, you need to type in a short summary (such as "Section 3.1 half done."). You can then click the commit button to save it to the local repository. GitHub desktop will then ask you if you want to "push" it, i.e. to upload it to the online repository, which you probably would like to.

When you restart working on a file, before opening the editor, please come back to GitHub desktop, and click the "Fetch origin" button in the top part of the window. If new changes by other collaborators are available, the button contains a smaller "pull" button to get the changes.

I'll be happy to give more details if you're stuck at some point, so please don't hesitate to ask me.