Overleaf v1 with GitHub / GitLab

2 minute read

Alternative: Switch from Overleaf to GitHub + Dropbox PDF sharing


The procedure below is for Overleaf v1 ONLY. The new Overleaf v2 uses GitHub directly. However, I don’t yet use Overleaf v2 with GitHub since it currently requires read/write permission to ALL GitHub repos, public and private! Overleaf should use GitHub Apps instead for granular permissions.

Note, I use GitLab for LaTeX with Overleaf v1 because of unlimited free private repos. You can of course swap in GitHub, Bitbucket, &c.

Backup your Overleaf v1 LaTeX document folder somewhere else now as a precaution. Once the procedure below is done, you’ll be able to:

git push
push local changes (after git commit) to GitLab and Overleaf v1 simultaneously
git push origin master
push local changes to only GitLab
git push overleaf master
push local changes to only Overleaf v1
git pull
pull from GitLab only
git pull overleaf master
pull from Overleaf v1 (normally just use GitLab)

Pick ONE of the following connections (1a) or (1b).

1a. Connect existing Overleaf v1 to GitLab

  1. check your current Overleaf v1 LaTeX repo
    cd ~/MyDissertation
    git remote -v
    

    You should see:

    origin  https://git.overleaf.com/hash (fetch)
    origin  https://git.overleaf.com/hash (push)
    
  2. Create a new repo MyDissertation in GitLab. Do not create any README, LICENSE, or .gitignore. Then connect GitLab as origin:
    git remote rename origin overleaf
    git remote add origin https://gitlab.com/username/MyDissertation
       
    git remote set-url origin --add --push https://git.overleaf.com/hash
    git remote set-url origin --add --push https://gitlab.com/username/MyDissertation
    

1b. Connect existing git repo to Overleaf v1

If you did the procedure above, you don’t need this procedure.

  1. if you haven’t already, clone your GitLab LaTeX repo to your PC.
    git clone https://gitlab.com/username/MyDissertation
    
  2. create a new blank Overleaf v1 project. Go into Share and copy the https://git.overleaf.com/hash. Rename in Overleaf main.tex to junk.tex
  3. connect Overleaf v1 as a second Git remote by
    git remote add overleaf https://git.overleaf.com/hash
    git remote set-url origin --add --push https://git.overleaf.com/hash
    git remote set-url origin --add --push https://gitlab.com/username/MyDissertation
    
  4. merge the blank Overleaf v1 project with
    git pull overleaf master
    

    you need --allow-unrelated-histories if using Git ≥ 2.9. if your Overleaf project is brand new

    git revert --mainline 1 HEAD
    
  5. finally update Overleaf v1, then visit to see your document there.
    git push overleaf master
    

2. Verify Overleaf v1 git remote setup

Verify setup by

git remote -v

and you should see:

origin  https://gitlab.com/username/MyDissertation (fetch)
origin  https://git.overleaf.com/<hash> (push)
origin  https://gitlab.com/username/MyDissertation (push)
overleaf https://git.overleaf.com/<hash> (fetch)
overleaf https://git.overleaf.com/<hash> (push)

SECURITY NOTE for GitHub with Overleaf v1

If you choose to also use GitHub public repos with public Overleaf v1 project, note that merge commits default log message reveals your “secret” Overleaf v1 URL, enabling anyone to edit your public Overleaf v1 project.

Use GitLab with unlimited free private repos instead of GitHub perhaps.

Mitigation: either of these will work to solve the security risk with public Overleaf v1 project secret URL. I choose to use a private GitLab repo.

  • make your Overleaf project private, so that a login/password is required to edit.
  • make your GitLab repo private–the number of pushes are still tracked to show you’re active.

Other possible Overleaf + Git configurations

  • SSH Public Key Authentication will also work (and is in general strongly recommended for any Git use)
  • You can simultaneously use Overleaf, GitLab, Dropbox, OneDrive, Bitbucket, &c. as many remotes as you want. Just remember to NOT put your active LaTeX files into a synced Dropbox/OneDrive folder or you’ll get synchronization errors. Let Git do its work properly.

Leave a Comment