Should I track the PDF in Git?

Generally no. PDFs are large binary files that don't diff well, bloating your repository. Instead, use CI/CD to generate PDFs automatically, or store them elsewhere (releases, cloud storage).

How do I handle merge conflicts in LaTeX?

LaTeX conflicts are resolved like any text file. Look for the conflict markers (<<<<<<), understand both versions, and manually merge the content. Using one sentence per line makes conflicts easier to resolve.

Should I use Git LFS for images?

For large or frequently-updated images, yes. Git LFS (Large File Storage) handles binary files better than regular Git. For small, rarely-changed images, regular Git is fine.

Version Control for LaTeX: The Complete Git Guide

Q: Should I use Git LFS for images?

For large or frequently-updated images, yes. Git LFS (Large File Storage) handles binary files better than regular Git. For small, rarely-changed images, regular Git is fine.

Why Git for LaTeX Projects?

You've spent hours perfecting your thesis formatting, only to find that a single misplaced command has thrown everything into disarray. Hunting through endless revisions can be a nightmare, but it doesn't have to be.

Git provides:

Complete history of every change you've ever made
Safe experimentation with branches you can delete if they fail
Collaboration with co-authors without emailing files back and forth
Backup to remote repositories like GitHub or GitLab
Recovery from any mistake by reverting to previous versions

This guide covers everything from basic setup to advanced team workflows.

Getting Started: Basic Git Setup

Initializing a Repository

Create a new repository for your LaTeX project:

# Navigate to your project folder
cd ~/Documents/my-thesis
 
# Initialize Git
git init
 
# Create initial commit
git add main.tex references.bib
git add chapters/ figures/
git commit -m "Initial commit: thesis structure"

Essential .gitignore for LaTeX

LaTeX generates many auxiliary files. Keep your repository clean with a proper .gitignore:

# LaTeX auxiliary files
*.aux
*.bbl
*.bcf
*.blg
*.fdb_latexmk
*.fls
*.log
*.out
*.run.xml
*.synctex.gz
*.synctex(busy)
*.toc
*.lof
*.lot
 
# Build output (optional - some prefer tracking)
*.pdf
 
# Editor files
*.swp
*~
.DS_Store
Thumbs.db
 
# IDE-specific
.idea/
*.sublime-*
.vscode/
 
# Temporary files
*.tmp
*.temp

Create this file in your repository root:

# Create .gitignore
cat > .gitignore << 'EOF'
*.aux
*.bbl
*.bcf
*.blg
*.log
*.out
*.toc
*.synctex.gz
EOF
 
git add .gitignore
git commit -m "Add .gitignore for LaTeX auxiliary files"

Connecting to Remote Repository

Push your work to GitHub, GitLab, or Bitbucket for backup and collaboration:

# Add remote (replace with your repository URL)
git remote add origin git@github.com:username/my-thesis.git
 
# Push main branch
git push -u origin main

Best Practices for LaTeX in Git

One Sentence Per Line

The single most impactful practice for LaTeX version control:

% Bad: paragraph as one line
This is a long paragraph about the methodology used in this research which covers several important aspects including the experimental setup and the statistical analysis.
 
% Good: one sentence per line
This is a long paragraph about the methodology used in this research.
The methodology covers several important aspects.
These include the experimental setup and the statistical analysis.

Benefits:

Better diffs: Changes to one sentence don't affect the entire paragraph
Easier review: See exactly what changed in each commit
Simpler conflicts: Merge conflicts are isolated to specific sentences
Readability: Line numbers reference specific sentences

Commit Messages That Make Sense

Write commit messages that your future self will understand:

# Bad
git commit -m "Update"
git commit -m "Fix stuff"
git commit -m "Changes"
 
# Good
git commit -m "Add methodology section with experimental design"
git commit -m "Fix equation numbering in results chapter"
git commit -m "Update references with 2024 publications"
 
# Great (with body for complex changes)
git commit -m "Restructure Chapter 3 for clarity
 
- Split 'Methods' into 'Data Collection' and 'Analysis'
- Move algorithm description to appendix
- Add summary section
 
Addresses reviewer comment #2"

Logical Commits

Group related changes together:

# Adding a new figure
git add figures/results-chart.pdf
git add chapters/results.tex  # References the figure
git commit -m "Add results chart with interpretation"
 
# Fixing a problem
git add chapters/intro.tex
git add references.bib
git commit -m "Fix missing citation in introduction"

Never commit:

Broken documents that don't compile
Temporary test changes
Binary files you'll regenerate

Branching Strategies for Academic Writing

Simple Strategy: Main + Feature Branches

For individual projects or small teams:

main (stable, always compiles)
├── chapter-3-draft
├── reviewer-revisions
└── experiments-appendix

# Start new section
git checkout -b chapter-3-draft
# ... work on chapter 3 ...
git add chapters/chapter3.tex
git commit -m "Draft Chapter 3 introduction"
 
# When ready, merge back
git checkout main
git merge chapter-3-draft
git branch -d chapter-3-draft  # Clean up

Multi-Author Strategy

For papers with multiple authors:

main (final version)
├── develop (integration branch)
│   ├── alice/methods
│   ├── bob/results
│   └── carol/discussion

Each author works on their branch:

# Alice works on methods
git checkout -b alice/methods develop
 
# Bob works on results
git checkout -b bob/results develop
 
# Integration: merge into develop
git checkout develop
git merge alice/methods
git merge bob/results
 
# When ready for submission
git checkout main
git merge develop
git tag v1.0-submission

Revision Strategy

For handling journal revisions:

# Before starting revisions
git tag v1-submitted
 
# Create revision branch
git checkout -b revision-round-1
 
# Address each comment (separate commits)
git commit -m "Address reviewer 1 comment on sample size"
git commit -m "Add requested sensitivity analysis"
git commit -m "Clarify methodology per reviewer 2"
 
# When done
git checkout main
git merge revision-round-1
git tag v2-revision-1

Handling Merge Conflicts

Understanding LaTeX Conflicts

When two people edit the same section, Git shows:

The results indicate that
<<<<<<< HEAD
our method outperforms the baseline by 15%.
=======
the proposed approach achieves 15% improvement over baseline methods.
>>>>>>> bob/results

Resolving Conflicts

Identify the conflict markers (<<<<<<<, =======, >>>>>>>)
Understand both versions
Decide which to keep (or combine them)
Remove the markers
Commit the resolution

# After resolving conflicts in your editor
git add conflicted-file.tex
git commit -m "Merge bob/results: combine wording for clarity"

Preventing Conflicts

Communicate: Tell co-authors what you're working on
Pull often: git pull before starting work
Divide work: Each author owns specific sections
Use branches: Isolate major changes
One sentence per line: Minimize conflict scope

Collaboration Workflows

Pull Request/Merge Request Workflow

For teams using GitHub or GitLab:

Author creates branch and pushes:

git checkout -b add-discussion-section
git push origin add-discussion-section

Author opens pull request on GitHub/GitLab
Reviewers comment on the changes
Author addresses feedback with additional commits
Maintainer merges when approved

Code Review for LaTeX

Review checklist for pull requests:

[ ] Document compiles without errors
[ ] Citations are complete and correct
[ ] Figures referenced correctly
[ ] Cross-references work
[ ] Consistent style and formatting
[ ] Spelling and grammar checked

Working with Non-Git Users

Sometimes co-authors don't use Git. Options:

Overleaf sync: Connect Git repo to Overleaf
Shared folder: You manage Git, they edit files
Manual merge: Accept changes via email, you commit

# After receiving edited file via email
cp ~/Downloads/chapter3-edited.tex chapters/chapter3.tex
git diff chapters/chapter3.tex  # Review changes
git add chapters/chapter3.tex
git commit -m "Incorporate Dr. Smith's edits to Chapter 3"

Advanced: CI/CD for LaTeX

Automated Compilation with GitHub Actions

Create .github/workflows/compile.yml:

name: Compile LaTeX
 
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Compile LaTeX
        uses: xu-cheng/latex-action@v3
        with:
          root_file: main.tex
          latexmk_use_xelatex: true
 
      - name: Upload PDF
        uses: actions/upload-artifact@v4
        with:
          name: thesis-pdf
          path: main.pdf
 
      - name: Create Release PDF
        if: github.ref == 'refs/heads/main'
        uses: softprops/action-gh-release@v1
        with:
          files: main.pdf
          tag_name: build-${{ github.sha }}

This automatically:

Compiles on every push
Checks that pull requests compile
Creates downloadable PDF artifacts
Publishes releases for main branch

GitLab CI Configuration

Create .gitlab-ci.yml:

image: texlive/texlive:latest
 
compile:
  script:
    - latexmk -pdf -xelatex main.tex
  artifacts:
    paths:
      - main.pdf
    expire_in: 1 week
 
pages:
  stage: deploy
  script:
    - mkdir public
    - cp main.pdf public/
  artifacts:
    paths:
      - public
  only:
    - main

Git Tips for Large Documents

Shallow Clones for Big Repositories

If your repository grows large:

# Clone only recent history
git clone --depth 10 git@github.com:user/thesis.git
 
# Later, get full history if needed
git fetch --unshallow

Git LFS for Binary Files

For large images or data files:

# Install Git LFS
git lfs install
 
# Track large file types
git lfs track "*.pdf"
git lfs track "*.png"
git lfs track "figures/*.eps"
 
# Add the tracking file
git add .gitattributes
git commit -m "Configure Git LFS for figures"

Squashing Messy History

Before merging a messy branch:

# Squash last 5 commits into one
git rebase -i HEAD~5
 
# In the editor, change 'pick' to 'squash' for commits to combine

Recovery Scenarios

Recovering Deleted File

# Find when file was deleted
git log --all --full-history -- "path/to/deleted-file.tex"
 
# Restore from before deletion
git checkout abc1234^ -- path/to/deleted-file.tex

Undoing a Bad Commit

# Undo last commit, keep changes staged
git reset --soft HEAD~1
 
# Undo last commit, keep changes unstaged
git reset HEAD~1
 
# Completely undo (destructive!)
git reset --hard HEAD~1

Finding Lost Work

# Find all recent commits, even on deleted branches
git reflog
 
# Recover lost commit
git checkout abc1234
git checkout -b recovered-work

Quick Reference

Daily Commands

git status           # What's changed?
git add <file>       # Stage changes
git commit -m "msg"  # Commit changes
git push             # Upload to remote
git pull             # Download from remote
git diff             # See unstaged changes

Branch Commands

git branch              # List branches
git checkout -b name    # Create and switch
git checkout name       # Switch to branch
git merge name          # Merge branch in
git branch -d name      # Delete branch

Collaboration Commands

git remote -v           # List remotes
git fetch origin        # Download without merging
git pull origin main    # Download and merge
git push origin branch  # Upload branch

Conclusion

Git transforms LaTeX document development from chaotic file management into a structured, collaborative process. The key practices:

One sentence per line for clean diffs
Meaningful commits for useful history
Branches for parallel development
Regular pushes for backup and sharing
CI/CD for automated compilation

Start simple—even basic version control beats none. As your needs grow, add branching strategies, collaboration workflows, and automation.

Your thesis is a major investment. Treat it like the important project it is.

Thetapad supports GitHub sync for seamless version control integration. Write in the browser, sync to your repository.

Why Git for LaTeX Projects?

Git provides:

Complete history of every change you've ever made
Safe experimentation with branches you can delete if they fail
Collaboration with co-authors without emailing files back and forth
Backup to remote repositories like GitHub or GitLab
Recovery from any mistake by reverting to previous versions

This guide covers everything from basic setup to advanced team workflows.

Getting Started: Basic Git Setup

Initializing a Repository

Create a new repository for your LaTeX project:

# Navigate to your project folder
cd ~/Documents/my-thesis
 
# Initialize Git
git init
 
# Create initial commit
git add main.tex references.bib
git add chapters/ figures/
git commit -m "Initial commit: thesis structure"

Essential .gitignore for LaTeX

LaTeX generates many auxiliary files. Keep your repository clean with a proper .gitignore:

# LaTeX auxiliary files
*.aux
*.bbl
*.bcf
*.blg
*.fdb_latexmk
*.fls
*.log
*.out
*.run.xml
*.synctex.gz
*.synctex(busy)
*.toc
*.lof
*.lot
 
# Build output (optional - some prefer tracking)
*.pdf
 
# Editor files
*.swp
*~
.DS_Store
Thumbs.db
 
# IDE-specific
.idea/
*.sublime-*
.vscode/
 
# Temporary files
*.tmp
*.temp

Create this file in your repository root:

# Create .gitignore
cat > .gitignore << 'EOF'
*.aux
*.bbl
*.bcf
*.blg
*.log
*.out
*.toc
*.synctex.gz
EOF
 
git add .gitignore
git commit -m "Add .gitignore for LaTeX auxiliary files"

Connecting to Remote Repository

Push your work to GitHub, GitLab, or Bitbucket for backup and collaboration:

# Add remote (replace with your repository URL)
git remote add origin git@github.com:username/my-thesis.git
 
# Push main branch
git push -u origin main

Best Practices for LaTeX in Git

One Sentence Per Line

The single most impactful practice for LaTeX version control:

% Bad: paragraph as one line
This is a long paragraph about the methodology used in this research which covers several important aspects including the experimental setup and the statistical analysis.
 
% Good: one sentence per line
This is a long paragraph about the methodology used in this research.
The methodology covers several important aspects.
These include the experimental setup and the statistical analysis.

Benefits:

Better diffs: Changes to one sentence don't affect the entire paragraph
Easier review: See exactly what changed in each commit
Simpler conflicts: Merge conflicts are isolated to specific sentences
Readability: Line numbers reference specific sentences

Commit Messages That Make Sense

Write commit messages that your future self will understand:

# Bad
git commit -m "Update"
git commit -m "Fix stuff"
git commit -m "Changes"
 
# Good
git commit -m "Add methodology section with experimental design"
git commit -m "Fix equation numbering in results chapter"
git commit -m "Update references with 2024 publications"
 
# Great (with body for complex changes)
git commit -m "Restructure Chapter 3 for clarity
 
- Split 'Methods' into 'Data Collection' and 'Analysis'
- Move algorithm description to appendix
- Add summary section
 
Addresses reviewer comment #2"

Logical Commits

Group related changes together:

# Adding a new figure
git add figures/results-chart.pdf
git add chapters/results.tex  # References the figure
git commit -m "Add results chart with interpretation"
 
# Fixing a problem
git add chapters/intro.tex
git add references.bib
git commit -m "Fix missing citation in introduction"

Never commit:

Broken documents that don't compile
Temporary test changes
Binary files you'll regenerate

Branching Strategies for Academic Writing

Simple Strategy: Main + Feature Branches

For individual projects or small teams:

main (stable, always compiles)
├── chapter-3-draft
├── reviewer-revisions
└── experiments-appendix

# Start new section
git checkout -b chapter-3-draft
# ... work on chapter 3 ...
git add chapters/chapter3.tex
git commit -m "Draft Chapter 3 introduction"
 
# When ready, merge back
git checkout main
git merge chapter-3-draft
git branch -d chapter-3-draft  # Clean up

Multi-Author Strategy

For papers with multiple authors:

main (final version)
├── develop (integration branch)
│   ├── alice/methods
│   ├── bob/results
│   └── carol/discussion

Each author works on their branch:

# Alice works on methods
git checkout -b alice/methods develop
 
# Bob works on results
git checkout -b bob/results develop
 
# Integration: merge into develop
git checkout develop
git merge alice/methods
git merge bob/results
 
# When ready for submission
git checkout main
git merge develop
git tag v1.0-submission

Revision Strategy

For handling journal revisions:

# Before starting revisions
git tag v1-submitted
 
# Create revision branch
git checkout -b revision-round-1
 
# Address each comment (separate commits)
git commit -m "Address reviewer 1 comment on sample size"
git commit -m "Add requested sensitivity analysis"
git commit -m "Clarify methodology per reviewer 2"
 
# When done
git checkout main
git merge revision-round-1
git tag v2-revision-1

Handling Merge Conflicts

Understanding LaTeX Conflicts

When two people edit the same section, Git shows:

The results indicate that
<<<<<<< HEAD
our method outperforms the baseline by 15%.
=======
the proposed approach achieves 15% improvement over baseline methods.
>>>>>>> bob/results

Resolving Conflicts

Identify the conflict markers (<<<<<<<, =======, >>>>>>>)
Understand both versions
Decide which to keep (or combine them)
Remove the markers
Commit the resolution

# After resolving conflicts in your editor
git add conflicted-file.tex
git commit -m "Merge bob/results: combine wording for clarity"

Preventing Conflicts

Communicate: Tell co-authors what you're working on
Pull often: git pull before starting work
Divide work: Each author owns specific sections
Use branches: Isolate major changes
One sentence per line: Minimize conflict scope

Collaboration Workflows

Pull Request/Merge Request Workflow

For teams using GitHub or GitLab:

Author creates branch and pushes:

git checkout -b add-discussion-section
git push origin add-discussion-section

Author opens pull request on GitHub/GitLab
Reviewers comment on the changes
Author addresses feedback with additional commits
Maintainer merges when approved

Code Review for LaTeX

Review checklist for pull requests:

[ ] Document compiles without errors
[ ] Citations are complete and correct
[ ] Figures referenced correctly
[ ] Cross-references work
[ ] Consistent style and formatting
[ ] Spelling and grammar checked

Working with Non-Git Users

Sometimes co-authors don't use Git. Options:

Overleaf sync: Connect Git repo to Overleaf
Shared folder: You manage Git, they edit files
Manual merge: Accept changes via email, you commit

# After receiving edited file via email
cp ~/Downloads/chapter3-edited.tex chapters/chapter3.tex
git diff chapters/chapter3.tex  # Review changes
git add chapters/chapter3.tex
git commit -m "Incorporate Dr. Smith's edits to Chapter 3"

Advanced: CI/CD for LaTeX

Automated Compilation with GitHub Actions

Create .github/workflows/compile.yml:

name: Compile LaTeX
 
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Compile LaTeX
        uses: xu-cheng/latex-action@v3
        with:
          root_file: main.tex
          latexmk_use_xelatex: true
 
      - name: Upload PDF
        uses: actions/upload-artifact@v4
        with:
          name: thesis-pdf
          path: main.pdf
 
      - name: Create Release PDF
        if: github.ref == 'refs/heads/main'
        uses: softprops/action-gh-release@v1
        with:
          files: main.pdf
          tag_name: build-${{ github.sha }}

This automatically:

Compiles on every push
Checks that pull requests compile
Creates downloadable PDF artifacts
Publishes releases for main branch

GitLab CI Configuration

Create .gitlab-ci.yml:

image: texlive/texlive:latest
 
compile:
  script:
    - latexmk -pdf -xelatex main.tex
  artifacts:
    paths:
      - main.pdf
    expire_in: 1 week
 
pages:
  stage: deploy
  script:
    - mkdir public
    - cp main.pdf public/
  artifacts:
    paths:
      - public
  only:
    - main

Git Tips for Large Documents

Shallow Clones for Big Repositories

If your repository grows large:

# Clone only recent history
git clone --depth 10 git@github.com:user/thesis.git
 
# Later, get full history if needed
git fetch --unshallow

Git LFS for Binary Files

For large images or data files:

# Install Git LFS
git lfs install
 
# Track large file types
git lfs track "*.pdf"
git lfs track "*.png"
git lfs track "figures/*.eps"
 
# Add the tracking file
git add .gitattributes
git commit -m "Configure Git LFS for figures"

Squashing Messy History

Before merging a messy branch:

# Squash last 5 commits into one
git rebase -i HEAD~5
 
# In the editor, change 'pick' to 'squash' for commits to combine

Recovery Scenarios

Recovering Deleted File

# Find when file was deleted
git log --all --full-history -- "path/to/deleted-file.tex"
 
# Restore from before deletion
git checkout abc1234^ -- path/to/deleted-file.tex

Undoing a Bad Commit

# Undo last commit, keep changes staged
git reset --soft HEAD~1
 
# Undo last commit, keep changes unstaged
git reset HEAD~1
 
# Completely undo (destructive!)
git reset --hard HEAD~1

Finding Lost Work

# Find all recent commits, even on deleted branches
git reflog
 
# Recover lost commit
git checkout abc1234
git checkout -b recovered-work

Quick Reference

Daily Commands

git status           # What's changed?
git add <file>       # Stage changes
git commit -m "msg"  # Commit changes
git push             # Upload to remote
git pull             # Download from remote
git diff             # See unstaged changes

Branch Commands

git branch              # List branches
git checkout -b name    # Create and switch
git checkout name       # Switch to branch
git merge name          # Merge branch in
git branch -d name      # Delete branch

Collaboration Commands

git remote -v           # List remotes
git fetch origin        # Download without merging
git pull origin main    # Download and merge
git push origin branch  # Upload branch

Conclusion

Git transforms LaTeX document development from chaotic file management into a structured, collaborative process. The key practices:

One sentence per line for clean diffs
Meaningful commits for useful history
Branches for parallel development
Regular pushes for backup and sharing
CI/CD for automated compilation

Start simple—even basic version control beats none. As your needs grow, add branching strategies, collaboration workflows, and automation.

Your thesis is a major investment. Treat it like the important project it is.

Thetapad supports GitHub sync for seamless version control integration. Write in the browser, sync to your repository.

Why Git for LaTeX Projects?

Getting Started: Basic Git Setup

Initializing a Repository

Essential .gitignore for LaTeX

Connecting to Remote Repository

Best Practices for LaTeX in Git

One Sentence Per Line

Commit Messages That Make Sense

Logical Commits

Never commit:

Branching Strategies for Academic Writing

Simple Strategy: Main + Feature Branches

Multi-Author Strategy

Revision Strategy

Handling Merge Conflicts

Understanding LaTeX Conflicts

Resolving Conflicts

Preventing Conflicts

Collaboration Workflows

Pull Request/Merge Request Workflow

Code Review for LaTeX

Working with Non-Git Users

Advanced: CI/CD for LaTeX

Automated Compilation with GitHub Actions

GitLab CI Configuration

Git Tips for Large Documents

Shallow Clones for Big Repositories

Git LFS for Binary Files

Squashing Messy History

Recovery Scenarios

Recovering Deleted File

Undoing a Bad Commit

Finding Lost Work

Quick Reference

Daily Commands

Branch Commands

Collaboration Commands

Conclusion

Frequently Asked Questions

Related Articles

Death to v3_final_REALLY_FINAL.docx: Modern Collaboration for Multi-Author Papers

The Complete Guide to Custom LaTeX Commands

LaTeX Keyboard Shortcuts: The Complete Productivity Guide

Why Git for LaTeX Projects?

Getting Started: Basic Git Setup

Initializing a Repository

Essential .gitignore for LaTeX

Connecting to Remote Repository

Best Practices for LaTeX in Git

One Sentence Per Line

Commit Messages That Make Sense

Logical Commits

Never commit:

Branching Strategies for Academic Writing

Simple Strategy: Main + Feature Branches

Multi-Author Strategy

Revision Strategy

Handling Merge Conflicts

Understanding LaTeX Conflicts

Resolving Conflicts

Preventing Conflicts

Collaboration Workflows

Pull Request/Merge Request Workflow

Code Review for LaTeX

Working with Non-Git Users

Advanced: CI/CD for LaTeX

Automated Compilation with GitHub Actions

GitLab CI Configuration

Git Tips for Large Documents

Shallow Clones for Big Repositories

Git LFS for Binary Files

Squashing Messy History

Recovery Scenarios

Recovering Deleted File

Undoing a Bad Commit

Finding Lost Work

Quick Reference

Daily Commands

Branch Commands

Collaboration Commands