Loading
Mar 30, 2015

How to synchronize an Overleaf LaTeX paper with a Github repository

overleaf_and_github

As a happy PeerJ user, I found out that I was eligible for a complimentary account at Overleaf (a.k.a. writeLaTeX). Overleaf is a collaborative writing and publishing system built around LaTeX. Strictly speaking, Overleaf is a Google Docs for LaTeX writers. It is neat and simple to use, to the point that it awakened my desire to use LaTeX again.

I encourage you to try it out. One of the features that I love about Overleaf is the integrated Git server for documents. This allows working off-line and 2-way synchronizing the changes with Overleaf server. Neat. Here is a nicely written review of the git feature and some example usage.

Scientists (not only computer scientists) are increasingly adopting Github for working on data and writing papers. Several papers, written publicly or through private repositories, are on Github’s git repositories. Overleaf does not yet offer a direct way to synchronize to Github git repositories1.

Luckily, there is a way to synchronize an article between Overleaf, a local computer, and a Github repository. This is because it is in git’s nature to be distributed (and decentralized, but this does not matter for us now). While this is quite simple for those accomplished with git, I understand that many users not from computer science might struggle in how to achieve this 3-way synchronization. That is why I explain how to achieve this below, using simple steps.

Suppose you have an Overleaf article at

https://www.overleaf.com/2029559gkypzx

.
Overleaf provides a related git repository at

https://git.overleaf.com/2029559gkypzx

.

Create a Github repository (public or private, it will work both ways). Let’s say that the repository is called

paper

, and it is reachable at

https://github.com/dgraziotin/paper.git

.

First, clone your Overleaf paper’s git repository

Overleaf git repository becomes the so called

origin

endpoint. You can optionally rename it to overleaf by giving the following from inside the paper folder:

Anytime you want to synchronize locally the changes done via Overleaf, you will pull from the overleaf repository.

Anytime you want to synchronize the local changes to Overleaf, you will commit a change (line 1) and push to the overleaf repository (line 5).

So far, so good. The same commands would have been used when employing a Github git repository 2. How about having both of them? We can add our Github repository with the following command:

Alright. Now we can pull from Overleaf and push to Github. There is the need to do a first code push.

From now own, a flow might be

git pull overleaf master

and

git push overleaf master

.

Of course, you could pull from overleaf, do some changes, commit, and push again to overleaf, then to Github. Or, you could pull from Github, do some changes, commit, and push again to Github and Overleaf. Still, there is some redundancy we can get rid of. How about pushing to both repositories? Let’s create an endpoint called

both

.

The first line creates a new remote repository URL called

both

. It points to Overleaf git server (again). However, the second command adds a new URL for pushing changes to the both endpoint, which points to the Github server. From now own, we can

push both

repositories at the same time (line 4).

The example above is a local change propagated to both Overleaf and Github. Finally, in order to propagate a change from Overleaf to local and Github, the following commands will be required.

That is all. Happy LaTeX writing!

  1. This feature has been requested.
  2. Please note that using Git with several people working on the same files is far more complicated than how it is shown here. There are many useful posts on how to use git with teams. Please take the time to read them.
written by dgraziotin

Dr. Daniel Graziotin received his PhD in computer science, software engineering at the Free University of Bozen-Bolzano, Italy. His research interests include human aspects in empirical software engineering with psychological measurements, Web engineering, and open science. He researches, publishes, and reviews for venues in software engineering, human-computer interaction, and psychology. Daniel is the founder of the psychoempirical software engineering discipline and guidelines. He is associate editor at the Journal of Open Research Software, academic editor at the Research Ideas and Outcomes (RIO) journal, and academic editor at the Open Communications in Computer Science journal. He is the local coordinator of the Italian Open science local group for the Open Knowledge Foundation. He is a member of ACM, SIGSOFT, and IEEE.

Comments
  • Diego Apr 18, 2015 Reply

    The registered changes in the “Versions” tab of the online editor, are registered as commits messages in the repository log.

    • dgraziotin Apr 18, 2015 Reply

      Yup. I actually appreciate this feature of Overleaf.

  • webaba Jul 7, 2015 Reply

    This is awesome, thanks man.

  • Chris Oct 8, 2015 Reply

    Am I missing something- I can push local changes to overleaf just fine, but if changes are made in overleaf, i cannot pull them down locally- I continue to get an “Already-up-to-date” message in my local repo. Is there some way I need to stage changes in Overleaf for git to recognize it? (that seems silly)

    • dgraziotin Oct 10, 2015 Reply

      Both ways are supposed to work. Are you using git pull overleaf master instead of the ordinary git pull?

  • Ross Oct 26, 2015 Reply

    Thanks for this; I got the basic setup working except for one big problem: Overleaf is rejecting a load of support files I have (e.g. a makefile I have for building locally).

    Have you encountered this and know a good way to work around it? I thought about selectively pushing only accepted files to Overleaf and pushing everything to Github, but it sounds messy no matter how I try to think about it.

    • dgraziotin Oct 27, 2015 Reply

      Hi Ross. Not yet, unfortunately. How about contacting them? I have just tweeted them about this issue. Let’s see what they think about it.

  • Natan Sep 13, 2016 Reply

    Thank you Daniel! This helped me today. 🙂 amazing.

Leave a comment