Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 38 ยท 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