Introduction
Git provides powerful version control for LaTeX documents, enabling collaboration and change tracking similar to software development. Just as programmers use Git to manage code versions, writers and researchers can leverage version control to track document evolution, collaborate seamlessly, and maintain a complete history of changes.
This guide covers Git strategies for LaTeX documents, from basic setup to advanced collaboration workflows.
Git Setup for LaTeX Projects
Creating .gitignore
A proper .gitignore prevents tracking compiled files and editor artifacts:
# Compiled LaTeX files
*.aux
*.bbl
*.blg
*.log
*.out
*.toc
*.synctex.gz
*.fdb_latexmk
*.fls
# Build outputs
*.pdf
build/
dist/
output/
# BibTeX cache
*.bib.bak
# Editor files
.vscode/
.idea/
*.swp
*.swo
*~
# OS files
.DS_Store
Thumbs.db
# Latexmk cache
.latexmk/
Initial Repository Setup
# Initialize repository
git init my-document
cd my-document
# Create directory structure
mkdir -p chapters figures bibliography
# Add LaTeX files
git add *.tex chapters/ figures/ bibliography/
git commit -m "Initial document structure"
Adding Remote Repository
# Add remote origin
git remote add origin https://github.com/username/my-document.git
# Or clone existing repository
git clone https://github.com/username/my-document.git
Branching Strategies
Feature Branch Workflow
The feature branch workflow isolates changes for review:
# Create new branch for a chapter or feature
git checkout -b new-chapter
# Make changes
vim chapter5.tex
git add chapter5.tex
git commit -m "Add introduction chapter"
# Switch back to main
git checkout main
# Merge when ready
git merge new-chapter
Git Flow for Documents
# Main branches
main # Production-ready versions
develop # Integration branch
# Feature branches
feature/chapter-1
feature/bibliography-update
# Hotfix branches
hotfix/citation-fix
Collaborative Branching
# Work on your own branch
git checkout -b review-literature
# Regularly sync with main
git fetch origin
git rebase origin/main
# Push your branch
git push origin review-literature
Collaboration Workflows
Pull Request Process
- Fork Repository: Create your own copy on GitHub
- Clone Locally:
git clone https://github.com/yourfork/document.git - Create Branch:
git checkout -b your-feature - Make Changes: Edit and commit your work
- Push Branch:
git push origin your-feature - Create PR: Submit changes for review
- Address Feedback: Make revisions as needed
Using GitHub for LaTeX
# Markdown README for LaTeX project
cat > README.md << 'EOF'
# My Thesis
This repository contains my PhD thesis written in LaTeX.
## Building
```bash
latexmk -pdf thesis.tex
Structure
chapters/- Chapter filesfigures/- Images and diagramsbibliography/- BibTeX files EOF
git add README.md git commit -m “Add README”
### GitHub Actions for LaTeX
```yaml
# .github/workflows/latex.yml
name: Build LaTeX
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install LaTeX
run: |
sudo apt-get update
sudo apt-get install -y texlive-latex-base
- name: Build PDF
run: latexmk -pdf main.tex
- name: Upload artifact
uses: actions/upload-artifact@v3
with:
name: document
path: main.pdf
Working with Large Files
Git LFS for Figures
# Install Git LFS
git lfs install
# Track large files
git lfs track "*.psd"
git lfs track "*.pdf"
git lfs track "*.png"
# Commit LFS configuration
git add .gitattributes
git commit -m "Configure Git LFS"
Referencing Figures
% Use relative paths
\documentclass{article}
\usepackage{graphicx}
\graphicspath{{figures/}}
\begin{document}
\begin{figure}
\centering
\includegraphics[width=0.8\textwidth]{diagram}
\caption{A diagram}\label{fig:diagram}
\end{figure}
\end{document}
Version Control Best Practices
Commit Messages
# Good commit messages
git commit -m "Add methodology chapter"
git commit -m "Update references with new citations"
git commit -m "Fix typo in abstract"
git commit -m "Revise conclusion based on feedback"
# Include issue numbers
git commit -m "Resolve #5: Add acknowledgments"
Commit Frequency
- Commit after completing logical units
- Don’t commit broken builds
- Write meaningful messages
- Review changes before committing
Tagging Versions
# Tag a version
git tag -a v1.0 -m "First complete draft"
git tag -a v1.1 -m "Revised after advisor feedback"
# List tags
git tag
# Push tags
git push origin --tags
Integration with Overleaf
Connecting Local Git to Overleaf
# Add Overleaf as remote
git remote add overleaf https://git.overleaf.com/username/project
# Push to Overleaf
git push overleaf main
# Pull from Overleaf
git pull overleaf main
Two-Way Sync
# Sync between local and Overleaf
git fetch overleaf
git merge overleaf/main
# Make changes locally
git push origin main
git push overleaf main
Conclusion
Git enables professional version control for LaTeX documents. Use feature branches for isolation, meaningful commit messages, and leverage GitHub Actions for automated builds. Integrate with Overleaf for cloud editing while maintaining local control.
Comments