This is a description of how I strongly prefer to manage the paper
writing process, and a rationale. If you are a student I am advising,
this is the default (but not 100% required method) for how we'll work
- source-of-truth repository on github/gitlab/bitbucket
- rebase commits before push
- use meaningful commit messages
- keep commits focused
- Paper text goes in text/
- Figures go in figures/
- Bibliographies go in bibs/
- One LaTeX file per-section
- Files have 1-2 word names
- Use the skeleton
A good paper edit commit has a specific job and changes only 1-2 files
of the paper, with the exception of spelling/grammar passes.
Commit messages should make it relatively clear what the objective of
the commit was and the list of changed files should make sense given
that objective. Unlike (good) code commits, it is OK if a paper edit
commit message might not make much sense a few months after being
Here are some commit examples from the Augury project:
"adds s5b rought draft, ports interesting oddities subsect into s5b removing subsubsects, adds some comments"
"address comments in result of aop v baseline existence experiment"
"added backref to discuss the XABC pattern in threatmodel"
LaTeX and git diffing works best when each sentence goes on its own
line. I encourage turning on visual line-wrapping in your editor of
choice, and turning on some sort of auto-reflow for
one-sentence-per-line. If you use emacs, I have a pile of bad elisp
for this behavior.
I prefer this methodolgy for four reasons:
- It makes it such that at a glance of git history, you can see who
has edited what recently in the paper, and why they did it.
- It encourages focusing on the text you are writing, not the
- It makes diffing across paper versions simpler.
- It means that Overleaf/etc going down on deadlines is not a concern.
A note on protocol for collaboration
A 'downside' (or maybe really a tradeoff) of this methodology is that
it may require taking "a lock" (asking for no one else to edit) on a
paper section during writing. This will need to be communicated to
your co-authors via email or slack. Don't take locks for more than 24
hours if you can.