Skip to content

Lesson 34 ยท Beamer, Tooling and Workflows

Version Control and Collaboration for LaTeX

Keep LaTeX projects in Git, ignore build files, write diff-friendly source, compare versions with latexdiff, collaborate on Overleaf and build PDFs in continuous integration.

A LaTeX project is plain text, which makes it ideal for version control. You can see every change, return to an older draft, work on a side branch for a risky rewrite and merge a co-author's edits. This lesson sets up a clean Git workflow, shows how to compare two versions of a document, covers online collaboration and automates PDF builds.

Starting a repository

TEXT
my-paper/
  main.tex
  preamble.tex
  chapters/
    intro.tex
    methods.tex
  figures/
    pipeline.pdf
  references.bib
  .latexmkrc
  .gitignore
  README.md
TEXT
git init
git add .
git commit -m "Initial draft"

What to ignore

Commit sources, not generated files:

TEXT
# .gitignore
*.aux
*.log
*.out
*.toc
*.lof
*.lot
*.bbl
*.blg
*.bcf
*.run.xml
*.fdb_latexmk
*.fls
*.synctex.gz
*.nav
*.snm
*.vrb
build/
_minted-*/
*.pdf          # optional: see below

Whether to commit the PDF depends on the project. For a paper, leave it out and publish releases or CI artifacts. For a CV that people download from the repository, commit it or attach it to a release. Keep large images in the repository only if they rarely change; for big binaries use Git LFS.

Diff-friendly writing

Git compares lines, so how you break lines decides how readable a diff is.

  • One sentence per line. A change to one sentence then affects one line, and merge conflicts are smaller.
  • Do not hard-wrap at 80 characters in the middle of sentences, because adding one word re-flows the paragraph.
  • Put each \item, table row and \includegraphics on its own line.
  • Keep figure files and tables in separate files so that conflicts remain local.
  • Use % comments sparingly and explain why, not what.

The stand-in below compares two versions of a paragraph line by line, to show why one sentence per line gives a precise diff.

JS Line diff of two drafts

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Branches and merging

  • Work on main for the stable draft and create a branch for each large change: git switch -c rewrite-intro.
  • Merge with git merge; resolve conflicts in the .tex file by editing the markers (<<<<<<<, =======, >>>>>>>), then rebuild to check it compiles.
  • Use tags for milestones: git tag submitted-v1, git tag revision-1. A tag is a snapshot you can rebuild exactly.
  • Write commit messages that say what changed in the content: "Rewrite introduction for clarity", not "update".

Co-authors should agree on who edits which file. Use \todo{} (package todonotes) or a comment macro such as \newcommand{\alice}[1]{\textcolor{red}{[Alice: #1]}} for notes, and remove them before submission.

Comparing versions with latexdiff

latexdiff makes a marked-up version of the document in which deletions are red and struck through and additions are blue, which is what referees and supervisors like to see.

TEXT
latexdiff old.tex new.tex > diff.tex
latexmk -pdf diff.tex

# compare against a Git revision directly
latexdiff-vc --git -r v1 -r HEAD main.tex
latexdiff --flatten old/main.tex new/main.tex   # follow \input and \include

For large projects, git-latexdiff wraps this process. If compilation of diff.tex fails, mark problem commands with --exclude-textcmd or change the --type markup option.

Collaborating online

Overleaf hosts LaTeX projects in the browser with real-time co-editing, comments, tracked changes, a history, templates for most journals and a Git bridge (premium) for syncing with GitHub. Share by link or invite by email.

Other options: a shared Git repository (GitHub, GitLab, Bitbucket) with each author editing locally; Dropbox-like sync is risky for .aux files, so keep generated files in an ignored build/ folder.

Agree on:

  1. The engine and class (record them in README.md or .latexmkrc).
  2. The bibliography tool (BibTeX or Biber) and a single .bib file with consistent keys.
  3. Macro names and notation in a shared preamble.tex.
  4. A policy for line breaking and comments.

Continuous integration

A build on every push catches broken documents before anyone else does. With GitHub Actions:

YAML
# .github/workflows/build.yml
name: Build PDF
on: [push, pull_request]
jobs:
  pdf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: xu-cheng/latex-action@v3
        with:
          root_file: main.tex
          latexmk_use_xelatex: false
      - uses: actions/upload-artifact@v4
        with:
          name: paper
          path: main.pdf

Pin versions of actions, and for reproducibility record TeX Live's year (the action offers a Docker image per year). The workflow produces a downloadable PDF for every commit.

Reproducibility checklist

  • All fonts and images are in the repository (or documented).
  • latexmk builds the PDF from a clean checkout with one command.
  • Figures are generated by scripts you also commit; the generated PDFs are listed in the build instructions.
  • You keep a final submission archive with sources, .bbl and the class files (many journals and arXiv require .bbl rather than .bib).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why write one sentence per line in a Git-tracked .tex file?

    Git compares whole lines; one sentence per line keeps changes local and conflicts small.
  2. 2. Which files should normally be left out of the repository?

    Generated files can be rebuilt; committing them only creates noisy diffs and conflicts.
  3. 3. What does latexdiff produce?

    latexdiff creates a document in which changes are coloured, ready for compilation.
  4. 4. What is the benefit of building PDFs in CI?

    A clean machine build shows missing files or packages that your own computer hid.

Summary

  • Track sources in Git and ignore auxiliary files; use .latexmkrc for settings.
  • Write one sentence per line and split large documents into files.
  • Use branches, tags and informative commit messages; resolve conflicts by editing and rebuilding.
  • latexdiff highlights changes between revisions; Overleaf offers browser collaboration.
  • CI builds a PDF per push and proves the project is reproducible.

Next: Project: A One-page Resume