A Git workflow for writing papers in Latex

Having used git to writing papers in collaboration with multiple authors, here’s the recipe that works well for me.

1. Split the document/paper into different files. Typically, each section of the document goes into a different file with one main.tex file combining the files into the document. It is best to split the document once all authors have agreed upon the structure of the document but before fleshing out the contents of the section. This avoids the avoid hassle of in-the-middle content reorganization. If a subsection is lengthy, then place them in a separate file.
2. Commit the .tex files into the master branch of the local Git repo
   git commit *tex
3. Push the master branch to the server, e.g., Bitbucket or GitHub.
   git push
4. Pick a section to work on (e.g., section 2) and communicate your choice to the collaborators. Good old email will suffice :)
5. Get the latest changes from the server.
   git pull
6. Create a branch in the local repo dedicated to this selected section, e.g., edit-sec2. We will refer to this section as the (your) current section.
   git branch edit-sec2
7. Checkout the branch for the current section.
   git checkout edit-sec2
8. Edit the section. Commit to the local repo as often as you like. I typically commit before any long break.
   git commit -a -m <message>
9. When you return from a break,
   a. check out the master branch: git checkout master
   b. pull the latest changes from the server: git pull
   c. checkout your current section branch: git checkout edit-sec2
   d. merge the master branch into your current section branch: git merge master
10. When you are done with your edits and are ready to share it with other authors,
    a. checkout master branch: git checkout master
b. pull the latest changes from the server: git pull
c. merge your current section branch into master branch: git merge edit-sec2
d. push changes to the server: git push
11. Repeat steps 4–10 for each section you want to edit.

Questions

Why not store the current section branch on the server? Some services like Overleaf only support one branch named master.

Why not use web-based editor with concurrent editing capability provided by services like Overleaf? Personal preference :) One could use a web-based editor. However, I prefer a local instance of Vim with Vim-Latex for focused edits and the web-based Overleaf editor for final edits done in conjunction with other authors.

What are other benefits of splitting the document into multiple files? Splitting helps create different variation of the document. For example, you can change the layout and cover sheet by modifying main.tex on a branch to generate a technical report variant of a document submitted for publication.

That’s it! Try it, tweak it, and let me know what you think :)

If you are interested, here’s another post about collaborative writing.

Tip: Add the following to your .gitconfig and use git wdiff when viewing diffs of text files; especially, if you write long lines of text.

[alias]
  wdiff = diff --color-words