A Workflow with GitHub and Overleaf

Required Softwares

For Linux

To run the script run.sh on Linux, you need to have the following software installed.

1. Git: For cloning repositories and managing version control.

2. Curl: For fetching contents from URLs.

3. Make: For running Makefile commands (if you use the makefile option).

Additionally, ensure you have a Bash shell available, which is typically pre-installed on most Linux distributions.

For Windows

You need to have the following software installed in Windows 10 to run the script run.bat mentioned in this post.

1. Git: This is required for cloning repositories and other Git operations. You can download it from git-scm.com.

2. PowerShell: This is included by default in Windows 10, so you don’t need to install it separately.

3. Make: If you are using the makefile command, you will need to have make installed. You can install it via GnuWin or through a package manager like Chocolatey with the command choco install make.

Make sure these tools are added to your system’s PATH so that they can be accessed from the command line.

Basic Idea

Basically, I will have two branches: master and overleaf. The master branch is for GitHub, and the overleaf branch is for Overleaf. I will push changes to GitHub from the master branch, and pull changes from Overleaf to the overleaf branch. I will also pull changes from Overleaf to the overleaf branch, merge these changes to the master branch, and push changes to GitHub. I will use the master branch as the main branch.

Initialization

1. Create a new empty repository on GitHub, note your repository ID, i.e., the part after https://github.com/<your-username>/ in the repository’s URL.
2. Create a blank Overleaf project, note your overleaf project ID, i.e., the part after https://www.overleaf.com/project/ in the project’s URL.
3. In your local PC, create a new directory for your LaTeX project, say test-project. Put your LaTeX files in this directory. For example, I will use my article template as the starting point.
4. Push the local project to GitHub.

   cd test-project
   git init
   git remote add origin <your-github-repo-url>
   git add --all .
   git commit -S -m "first commit $(date +'%Y-%m-%d  %H:%M:%S %Z')" 
   # you can change the message and remove -S if you don't sign your commits
   git push -u origin master
   

5. Create a new overleaf branch, merge the master branch to the overleaf branch, and push the overleaf branch to GitHub and Overleaf.

   git checkout --orphan overleaf
   git rm -rf .
   git remote add overleaf https://git@git.overleaf.com/<your-overleaf-project-id>
   git pull overleaf master --allow-unrelated-histories
   

   Before continuing, you need to manually modify the content of .git/config file. Check if something like the following is there:

   [remote "overleaf"]
       url = https://git@git.overleaf.com/<your-overleaf-project-id>
       fetch = +refs/heads/*:refs/remotes/overleaf/*
       pushurl = https://git@git.overleaf.com/<your-overleaf-project-id>
   [branch "overleaf"]
       remote = overleaf
       merge = refs/heads/master
   

   If not, add it. Then, push the overleaf branch to GitHub and Overleaf.

   git merge --no-commit --no-ff --allow-unrelated-histories master
   # Delete any file you do not want to upload to Overleaf
   git add --all .
   git commit -S -m "Merge master onto overleaf $(date +'%Y-%m-%d  %H:%M:%S %Z')" 
   # you can change the message and remove -S if you don't sign your commits
   git push -u origin overleaf # push to GitHub 'overleaf' branch
   git push overleaf overleaf:master # push to Overleaf
   

Workflow

Now, you have a copy of the LaTeX project on your computer, GitHub, and Overleaf.

Work on the project on your computer, push changes to GitHub and Overleaf

To make sure you do not miss any changes, pull changes from GitHub and Overleaf before you start working on the project.

git pull --all

If there is any change from the overleaf branch, merge it to the master branch.

git checkout overleaf
git push -u origin overleaf # push to GitHub 'overleaf' branch
git checkout master
git merge --no-commit --no-ff --allow-unrelated-histories overleaf
git commit -S -m "Merge overleaf onto master $(date +'%Y-%m-%d  %H:%M:%S %Z')"
git push -u origin master # push to GitHub 'master' branch

OK, now you can work on the project locally. After you finish, push changes to GitHub and Overleaf. First, push changes to GitHub.

git add --all .
git commit -S -m "Your commit message $(date +'%Y-%m-%d  %H:%M:%S %Z')"
git push -u origin master

Then, merge changes to overleaf branch and push changes to both GitHub and Overleaf.

git checkout overleaf
git merge --no-commit --no-ff --allow-unrelated-histories master
# Delete any file you do not want to upload to Overleaf
git add --all .
git commit -S -m "Merge master onto overleaf $(date +'%Y-%m-%d  %H:%M:%S %Z')"
git push -u origin overleaf # push to GitHub 'overleaf' branch
git push overleaf overleaf:master # push to Overleaf

Work on the project on Overleaf, pull changes from Overleaf to your local copy, and sync with GitHub

To pull changes from Overleaf to your local copy

git checkout overleaf
git pull overleaf master

To sync with GitHub

git checkout overleaf
git push -u origin overleaf # push to GitHub 'overleaf' branch
git checkout master
git merge --no-commit --no-ff --allow-unrelated-histories overleaf
git commit -S -m "Merge overleaf onto master $(date +'%Y-%m-%d  %H:%M:%S %Z')"
git push -u origin master # push to GitHub 'master' branch

Work on the project on GitHub, sync with Overleaf and your local copy

You can also work on the project on GitHub using GitHub Codespaces. For this purpose, you need to configure your codespace by creating a .devcontainer directory with a devcontainer.json file. You can use my devcontainer.json as a starting point. Additionally, you can also see my .gitignore file.

To start, create .devcontainer directory and put devcontainer.json in it. Then, push the changes to GitHub.

git checkout master
git add .devcontainer
git commit -S -m "Add .devcontainer $(date +'%Y-%m-%d  %H:%M:%S %Z')"
git push -u origin master

Now, you can go to your GitHub repository, click on the Code button, and select Open with Codespaces. After the codespace is created, you can work on the project on GitHub.

Once you finish, you can push changes to GitHub and Overleaf using the same steps as when you work on the project on your computer. Finally, you can pull changes to your local copy by simply running

git pull --all