Overleaf Git Integration

If your experiment code lives in a GitHub repository and your paper lives on Overleaf, you have probably done the upload dance: rerun an experiment, hunt down the regenerated figure on disk, open Overleaf, delete the old file, upload the new one, and repeat for every figure and table that changed. It is slow, it is easy to leave a stale figure behind, and it leaves no record of which version of your code produced which figure in the paper.

Overleaf Premium's GitHub Synchronization feature removes most of this busywork. This article describes one particular way to use it: cloning the paper's repository inside your experiment repository, in a directory that the experiment repository ignores. Your analysis scripts then write figures and tables straight into the paper, and a single push sends them to Overleaf.

Important: Overleaf Premium is required
GitHub Synchronization is a paid Overleaf feature. Check whether you already have access through an institutional license before paying for it yourself. If you don't use Git yet, read up on the basics first, since this workflow assumes you are comfortable with clone, commit, push, and pull.

How It Works

There are several ways to connect a code repository to an Overleaf project. In this one, the two repositories stay completely independent. The paper repository is cloned into a subdirectory (here called paper/), and that subdirectory is listed in the experiment repository's .gitignore. The experiment repository never records anything about the paper, and the paper repository never sees your experimental code. Your scripts simply write files into a folder that happens to be a different Git repository.

The final layout looks like this:

my-experiments/                 ← experiment repo (github.com/you/my-experiments)
├── .gitignore                  ← contains "paper/"
├── src/
├── scripts/
│   └── make_figures.py         ← writes into paper/figures and paper/tables
├── Makefile
└── paper/                      ← SEPARATE git repo, ignored by the outer repo
    ├── .git/                   ← points to github.com/you/my-paper
    ├── main.tex
    ├── refs.bib
    ├── figures/                ← written by code
    │   └── coverage.pdf
    └── tables/                 ← written by code
        └── results.tex

Generated figures and tables flow from your code to Overleaf, and prose written on Overleaf flows back to your local copy:

scripts/make_figures.py ──writes──▶ paper/figures, paper/tables
paper/   ──git push──▶  GitHub (my-paper)  ──"Pull GitHub changes"──▶  Overleaf
Overleaf ──"Push Overleaf changes"──▶  GitHub (my-paper)  ──git pull──▶  paper/

Strengths	Weaknesses
No More Uploading: Regenerated figures and tables reach the paper with one commit and one push, no manual file shuffling required. Clean Histories: Paper edits never clutter your code history, and code changes never clutter your paper history. No Coupled Tracking: Unlike git submodules, you never need an extra "update the paper pointer" commit in your experiment repository every time the paper changes. Collaborator Friendly: Co-authors can keep writing on Overleaf as usual. Nothing about their workflow changes.	Sync Is Manual: Overleaf does not watch GitHub. Someone has to click a button in Overleaf to pull new changes in (and to push Overleaf edits out). Provenance Is Up to You: Because the repositories are not linked, the only record of which code produced a figure is whatever you write in the paper's commit messages. A small script (below) handles this for you. One More Thing to Clone: Anyone who wants to regenerate the paper's figures needs to clone the paper repository separately.
🔗 Overleaf Documentation: GitHub Synchronization

Setting It Up

Step 1: Link Overleaf to GitHub

In Overleaf, open Account Settings and find the GitHub entry under the project synchronization section. Click Link and authorize Overleaf in the GitHub dialog that pops up.

File:Overleaf-account-settings-github-link.png

Linking a GitHub account from Overleaf's account settings.

Step 2: Create a GitHub repository from your Overleaf project

Open your paper in Overleaf, click Menu in the top left, and choose GitHub under the Sync section. Select Create a GitHub repository, give it a name (e.g. my-paper), and make it private. Overleaf then pushes the current contents of your project to the new repository.

File:Overleaf-menu-sync-github.png

The GitHub entry in the Overleaf project menu.

File:Overleaf-create-github-repo.png

Creating the paper repository from Overleaf.

Tip: Already have the paper on GitHub?
You can go the other direction instead. In Overleaf, choose New Project → Import from GitHub and select your existing repository.

Step 3: Clone the paper inside your experiment repository

From the root of your experiment repository, tell Git to ignore the paper/ directory before you clone into it:

cd my-experiments
echo "paper/" >> .gitignore
git add .gitignore
git commit -m "Ignore nested paper clone"

git clone git@github.com:you/my-paper.git paper

Then check that the two repositories don't see each other:

git status          # should NOT list paper/
git -C paper status # shows the paper repo, on its own branch

File:Nested-clone-git-status.png

The outer repository ignores paper/; the inner repository is independent.

Warning: Don't skip the .gitignore entry
Without it, a careless git add . in the experiment repository will register paper/ as an "embedded repository," which confuses collaborators and anything else that clones your code. If this happens, git rm --cached paper undoes it.

Step 4: Point your code at the paper directory

Rather than hard-coding paths in every script, define the paper location once. Using an environment variable with a sensible default means the code still runs for people who haven't cloned the paper (their figures just land in an ignored folder).

# src/paths.py
import os
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[1]
PAPER_DIR = Path(os.environ.get("PAPER_DIR", REPO_ROOT / "paper"))
FIG_DIR = PAPER_DIR / "figures"
TAB_DIR = PAPER_DIR / "tables"

FIG_DIR.mkdir(parents=True, exist_ok=True)
TAB_DIR.mkdir(parents=True, exist_ok=True)

For figures, save vector PDFs directly into the paper. Removing the creation timestamp means a figure that didn't actually change produces an identical file, so Git won't report a pointless change:

import matplotlib.pyplot as plt
from src.paths import FIG_DIR

fig, ax = plt.subplots(figsize=(3.25, 2.4))   # match your template's column width
...
fig.savefig(FIG_DIR / "coverage.pdf", bbox_inches="tight",
            metadata={"CreationDate": None})

For tables, write a LaTeX fragment rather than a full document:

from src.paths import TAB_DIR

tex = df.to_latex(index=False, escape=True, float_format="%.3f")
(TAB_DIR / "results.tex").write_text(tex)

and pull both into the paper as usual:

\includegraphics[width=\linewidth]{figures/coverage}
...
\input{tables/results}

For numbers quoted in the text, the same idea works. Have your code write LaTeX macros so the prose never goes stale:

(TAB_DIR / "numbers.tex").write_text(
    f"\\newcommand{{\\coverageNinetyFive}}{{{cov95:.1f}\\%}}\n"
)

% preamble
\input{tables/numbers}
% body
Our intervals achieve \coverageNinetyFive{} empirical coverage.

Day-to-Day Workflow

Sending new results to the paper

After rerunning your experiments, commit and push from inside paper/:

python scripts/make_figures.py

cd paper
git pull                         # pick up any text edits pushed from Overleaf first
git add figures tables
git commit -m "Regenerate figures from my-experiments@$(git -C .. rev-parse --short HEAD)"
git push

Then, in Overleaf, open Menu → GitHub and click Pull GitHub changes into Overleaf.

File:Overleaf-pull-github-changes.png

Bringing the regenerated figures into Overleaf.

Important: Overleaf does not sync automatically
Overleaf only picks up changes from GitHub when someone clicks the pull button, and only sends its own changes to GitHub when someone clicks the push button. Forgetting the pull is by far the most common reason the paper still shows old figures.

The commit message above includes the short hash of your experiment repository. Since the two repositories aren't linked, this message is your record of which code produced which figure. Running git log -- figures/coverage.pdf inside paper/ will answer "where did this figure come from?" months later.

Automating it with a Makefile

Once the steps above feel familiar, wrap them in a single command:

PAPER := paper
SHA   := $(shell git rev-parse --short HEAD)$(shell git diff --quiet || echo -dirty)

.PHONY: figures paper-sync

figures:
	python scripts/make_figures.py

paper-sync: figures
	git -C $(PAPER) pull --rebase
	git -C $(PAPER) add figures tables
	git -C $(PAPER) diff --cached --quiet || \
	  git -C $(PAPER) commit -m "Regenerate figures from my-experiments@$(SHA)"
	git -C $(PAPER) push
	@echo "Now click 'Pull GitHub changes into Overleaf' in the Overleaf GitHub menu."

Now make paper-sync regenerates everything, skips the commit if nothing actually changed, marks the commit -dirty if your experiment code had uncommitted changes, and reminds you to pull in Overleaf.

When co-authors edit on Overleaf

Before regenerating figures locally, push any Overleaf edits out to GitHub (Menu → GitHub → Push Overleaf changes to GitHub) so that the git pull in paper/ picks them up.

File:Overleaf-push-to-github.png

Sending Overleaf edits back to GitHub.

Avoiding conflicts

Conflicts are rare if every file has exactly one "owner":

figures/ and tables/ belong to your code. Never edit them by hand on Overleaf; the next regeneration will silently overwrite your changes. Change the formatting in the code that generates them instead.

.tex and .bib files belong to people. Write them on Overleaf (or locally, then push), and always pull before you push figures.

Why Not a Git Submodule?

Git submodules are the "official" way to put one repository inside another, so it is natural to ask why this workflow avoids them.

	Gitignored Clone	Git Submodule	Git Subtree
Experiment repo records the paper version	No	Yes (a pointer)	Yes (full history)
Extra commit in experiment repo per paper change	No	Yes	Yes
Paper history mixed into code history	No	No	Yes
Special clone instructions for collaborators	No	--recurse-submodules	No
Link between figure and code version	Commit message	Automatic	Automatic

A submodule gives you exact, automatic provenance, but at a price: every change to the paper, including every typo fix a co-author pushes from Overleaf, needs a matching "bump the submodule" commit in your experiment repository. For a paper that is edited daily, that noise usually isn't worth it. The gitignored clone trades automatic provenance for a scripted commit message, which is plenty in practice.

Variations

Skip GitHub with Overleaf's Git integration: Overleaf Premium also lets you clone a project directly (git clone https://git.overleaf.com/<project-id>, using a Git token generated in Account Settings). Clone that into the gitignored directory instead, and a git push lands in Overleaf immediately with no pull button. The catch is that you no longer get a GitHub copy of the paper for issues, reviews, or backups.

Generating figures on a cluster: Clone the paper repository on the cluster as well and run make paper-sync there. Alternatively, point PAPER_DIR at a scratch directory on the cluster, copy the outputs back to your laptop, and push from there.

Common Pitfalls

Things to Watch Out For

Forgetting the Overleaf pull: Your figures are on GitHub, but Overleaf still shows the old ones. The reminder in the Makefile helps. Pushing from both sides at once: If Overleaf has unpushed edits and GitHub has new figures, Overleaf has to merge them. Push from Overleaf first, pull locally, then push your figures. Bloating the paper repository: PNGs and timestamped PDFs change on every run. Prefer vector PDFs with the timestamp removed, and only commit figures that actually changed. Overleaf project limits: Overleaf limits project size and file counts. Keep raw outputs, checkpoints, and intermediate data in the experiment repository (or out of Git entirely); only put paper-ready figures and tables in paper/. Working on branches: Overleaf only syncs one branch. Stick to the default branch inside paper/; anything on another branch won't show up in Overleaf.

Note: This is just one of several ways to connect your code and your paper. If the manual pull button bothers you, try the Git integration variation above; if you want airtight provenance, a submodule may be worth the extra commits.