Git and Overleaf integration
Author
Santiago Casas
License
Creative Commons CC BY 4.0
Abstract
A small guide on how to set up Overleaf and Github and your local repo to have a comfortable two-way interaction.
A small guide on how to set up Overleaf and Github and your local repo to have a comfortable two-way interaction.
\documentclass[a4paper]{article}
\usepackage[english]{babel}
\usepackage[utf8x]{inputenc}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage[colorinlistoftodos]{todonotes}
\usepackage{hyperref}
\usepackage{listings}
\title{Git and Overleaf integration}
\author{Santiago Casas}
\begin{document}
\maketitle
\section{Option 1: Start with a local project and push it to Overleaf}
\begin{enumerate}
\item You must have a git repository (for example on github) where your \LaTeX project is located.
\item You should have a local clone (via git clone) of your project.
\item Then create a new empty Overleaf project that you are going to overwrite later.
\item Using the "Share" button, find the git address of your new Overleaf project.
\item Then follow these \href{https://www.overleaf.com/help/230-how-do-i-push-a-new-project-to-overleaf-via-git#.V7NMWLNnthE}{instructions on the overleaf help site} in order to pull the Overleaf project and then overwrite your local \LaTeX project onto it and finally push it to the overleaf remote server.
\item Now your local git repository will have two remotes: overleaf and origin. (origin is the default name used by services like gitlab or github).
\item Ideally, after you do changes on your local \LaTeX copy, you would like to push to both remotes, overleaf and your github repo. So, type the following commands to do that (replacing the correct address to your repositories):
\begin{itemize}
\item \verb|git remote set-url --add --push origin git@github.com:myrepo.git|
\item \verb|git remote set-url --add --push origin https://git.overleaf.com/xyz1234|
\end{itemize}
\item The command \verb|git pull| executed on your master branch will only pull from the repository to which the master branch is pointing to. The normal case, is that master is pointing to origin. If you which to change that, there are two options: Either type \texttt{git config branch.master.remote overleaf} \textbf{or} type \texttt{git config -e} and modify your config file, such that it looks something like this (here only the relevant parts are shown):
\begin{lstlisting}
[remote "origin"]
url = git@github.com:myrepo.git
fetch = +refs/heads/*:refs/remotes/origin/*
pushurl = git@github.com:myrepo.git
pushurl = https://git.overleaf.com/xyz1234
[branch "master"]
remote = overleaf
merge = refs/heads/master
[branch "mylatex"]
remote = origin
merge = refs/heads/mylatex
[remote "overleaf"]
url = https://git.overleaf.com/xyz1234
fetch = +refs/heads/*:refs/remotes/overleaf/*
pushurl = git@github.com:myrepo.git
pushurl = https://git.overleaf.com/xyz1234
\end{lstlisting}
Here we have two remotes, origin and overleaf. The master branch points to overleaf, while the mylatex branch points to origin. The mylatex branch is not necessary at all, is just an example. So that when located on the master branch a simple git pull will pull changes from the overleaf remote. On the mylatex branch it will be from the origin remote (which is github).
\item Now you can push to both remotes if you do either \texttt{git push} or \texttt{git push origin master} or \texttt{git push overleaf master}, since both remotes contain both pushurl's.
\item However there is no way to update or fetch changes from both remotes at the same time and it also wouldn't make sense. Therefore if you want to fetch from both remotes, just type:
\texttt{git fetch --all}. This will check for changes on both remotes and then you can decide from which remote to pull or to pull from the standard one. \todo{Check the git \href{https://git-scm.com/book/ch3-5.html}{documentation} for more help about this.}
\item The whole point about this Overleaf-Git(hub) integration is that now your collaborators can work on github, gitlab or any other service or directly on the overleaf website and everything will be synced almost automatically.
\item Overleaf pushes a new commit to its repo any time there are new changes, while if you work locally, you need to push to github and overleaf to maintain them updated. The new changes will then be reflected on Overleaf immediately. On the other hand, new changes from Overleaf have to be pulled locally and then pushed to github manually.
\end{enumerate}
\section{Option 2: Start a project on Overleaf and then push it to a github repository}
\begin{enumerate}
\item This option is a bit easier and will be left as an exercise to the reader.
\item The main steps are:
\begin{itemize}
\item Create a project on Overleaf and find its repo address.
\item Clone locally and then push to a new repo on github.
\item Change your config files so that automatically changes are pushed to both repos.
\item Configurate your git and decide from which repo to pull by default.
\end{itemize}
\end{enumerate}
\thanks{ Thanks to everyone on stack exchange for the kind help and to the Overleaf team for its good help section.}
\end{document}