Skip to content
Ahmad Ammar

8. Good practice and version control

8.1 A tidy project

paper/
  main.tex        the document's skeleton
  sections/       one file for each section
  figures/        generated by scripts
  tables/         generated by scripts
  refs.bib
  code/           scripts that make the figures, tables and numbers
  build/          outputs, not tracked

8.2 Version control

LaTeX is text, so Git handles it well. Put each sentence on its own line, so that a change shows as one changed sentence. Keep helper files out of Git with a .gitignore:

*.aux
*.log
*.out
*.toc
*.bbl
*.blg
*.synctex.gz

Tag each version you send out, as covered in the Git and automation guide.

8.3 Reproducible builds

A document is reproducible if someone else can rebuild it from your files.

  • Record the commands in a README or a script.

  • Generate figures, tables and numbers with code.

  • Build in a clean folder now and then, because old helper files can hide faults.

  • Keep paths relative, never tied to your own machine.

  • Fix \date{...} to a real date for a version, because \today changes at every compile.

8.4 Accessible documents

  • Use real headings, lists and captions.

  • Choose colours with good contrast that still work in greyscale.

  • Prefer colourblind-safe palettes.

  • Set the document's title and language, for screen readers: \hypersetup{pdftitle={...}}.

8.5 Working with others

Overleaf offers live co-editing, and it can sync with Git. Otherwise, agree who changes what, keep to one sentence per line, and use latexdiff old.tex new.tex > changes.tex to produce a marked-up comparison for readers who don't use Git.