- 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
Paper CommitsA good paper edit commit has a specific job and changes only 1-2 files of the paper, with the exception of spelling/grammar passes.
Commiting/adding large images (e.g. temporary diagrams) will make the repo and pdf difficult to handle. If you are adding a photo of a temp diagram, downscale it first. This can be done with many tools, e.g. with imagemagick's 'convert':
convert INPUT_FILE -resize 400x300 OUTPUT_FILE
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 written.Here are some commit examples from the Augury project:
"adds s5b rought draft, ports interesting oddities subsect into s5b removing subsubsects, adds some comments" edits: reversing.tex "address comments in result of aop v baseline existence experiment" edits: existence.tex "added backref to discuss the XABC pattern in threatmodel" edits: existence.tex threatmodel.tex "Spell checks" edits: DMPs.tex abstract.tex background.tex existence.tex introduction.tex
Style notesLaTeX 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.
Why?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 rendered PDF.
- It makes diffing across paper versions simpler.
- It means that Overleaf/etc going down on deadlines is not a concern.