Overleaf‐GitHub Synchronization

This guide outlines a streamlined process for synchronizing the GitHub development(issue) branch with Overleaf, allowing you to collaborate on .tex documents. When there is an issue that requires to make edits on Overleaf, the approach is as follows:

Workflow

1. Set up Dropbox sync to Overleaf.
2. User imports the relevant /paper_slides/ directory to Overleaf manually (using New Project -> Upload Project), creating a mirror project.
3. For text edits, users collaborates on editing on Overleaf.
4. To upload new or changed inputs(tables, figures) to Overleaf, change it in the synced Dropbox directory. Users are allowed to use the new /paper_slides/input/ folder to dropbox to replace the old one.
5. When ready to commit, User exports the content from Overleaf to the local clone of the development branch manually (using Download -> Source), replace the files in original /paper_slides/code/ directory, and then commits.

Notice

1. Dropbox Synchronization is an Overleaf premium feature. Please make sure you have the subscription of Overleaf premium.
2. Dropbox sync does not have a brake/warning for file conflicts, so every user need to be very careful to (1) always instantly update the changes in /input/ both on github and dropbox-sync; (2) rebase collaborator's commit before updating to dropbox-sync.
3. Collaborators are suggested to modify .tex files only on the overleaf, because we don't commit our .tex changes until the end of issue.

Manage difference between Overleaf compile and local Tex compile

Overleaf uses the latest version of TexLive to compile, and we can always shift to old TexLive versions. For details please refer to the official blog here. Lab-members need to set the TexLive version in local end consistent with the version in Overleaf to avoid seeing difference between the outputs. If in some projects, collaborators use a different TeX distribution (e.g., MiKTeX), to trying avoid compile failure, we should use the packages that only are part of the standard TeX distribution and specify old package versions in those projects.

Alternative workflow

The option proposed has some drawbacks referred here. If we expect the scope of issue is big and last for long time, this manual options require to upload inputs every time when there's new commit, and is vulnerable to potential failure points.

We recommend an alternative workflow using a mirror repository with automation, this provide a solution of directly sync overleaf to github issue branches without manual steps. Details can be referred in the attached PDF. This workflow requires a relative high fixed cost of setting up, and is not suggested to be a standard workflow for all issues.

mirror-repo-workflow.pdf