Skip to content

feat: ignore LaTeX build artifacts and add .olignore support #19

@aloth

Description

@aloth

What would you like?

Local LaTeX compilers (pdflatex, latexmk, xelatex, lualatex) drop build artifacts next to source files:

*.aux *.bbl *.blg *.log *.out *.toc *.lof *.lot
*.fls *.fdb_latexmk *.synctex.gz *.nav *.snm *.vrb
*.idx *.ind *.ilg *.glo *.gls *.glg *.bcf *.run.xml
*.xdv *.dvi

olcli sync happily uploads these to Overleaf, which causes:

  1. Compile failures — Overleaf's server can't write its own thesis.aux because a stale one is pinned.
  2. Wrong PDF output — Overleaf compiles against the stale .bbl instead of regenerating it, producing incorrect bibliographies.
  3. Repo noise — collaborators see dozens of binary artifacts.

This is a footgun for anyone who occasionally compiles locally for offline work.

Use case / why this matters:

Layer 1: built-in ignore list (always on, opt-out)

const DEFAULT_LATEX_IGNORE = [
  // LaTeX build artifacts
  '*.aux', '*.bbl', '*.blg', '*.log', '*.out', '*.toc',
  '*.lof', '*.lot', '*.fls', '*.fdb_latexmk', '*.synctex.gz',
  '*.nav', '*.snm', '*.vrb', '*.idx', '*.ind', '*.ilg',
  '*.glo', '*.gls', '*.glg', '*.acn', '*.acr', '*.alg',
  '*.bcf', '*.run.xml', '*.xdv', '*.dvi',
  // Editor / OS noise
  '.DS_Store', 'Thumbs.db', '*.swp', '*.swo', '*~',
  // Common build dirs
  '_minted-*/', 'build/', 'out/',
];

Layer 2: .olignore (project-level, gitignore syntax)

# .olignore
*.draft.tex
notes/
chapters/scratch/
!important.aux       # negation: keep this one

Use the ignore npm package (~30KB, zero deps, used by ESLint/Prettier).

Layer 3: .olignore.local (machine-specific, never synced)

For "ignore on this machine but not for collaborators." Mirrors .gitignore vs .git/info/exclude.

Special case: *.pdf

The PDF is sometimes the deliverable, sometimes build noise. Rule: ignore X.pdf only if X.tex exists in the same folder. This kills thesis.pdf next to thesis.tex but preserves a hand-uploaded figures/diagram.pdf.

CLI surface

olcli sync                       # defaults + .olignore (default)
olcli sync --no-default-ignore   # only .olignore applies
olcli sync --no-ignore           # everything goes (escape hatch)
olcli sync --dry-run --verbose   # show what's filtered
olcli ignored                    # list patterns currently in effect

One-time migration warning

After upgrade, on first sync, scan remote against new ignore rules:

⚠️  Found 6 LaTeX build artifacts on remote that match the new ignore rules:
    thesis.aux, thesis.bbl, thesis.blg, thesis.log, thesis.out, thesis.pdf
    Run `olcli clean-remote --apply` to delete them on Overleaf.

Reuses the manifest-diff machinery added in #7 - different action.

Any alternatives you've considered?

# Approach Verdict
1 Hardcoded built-in ignore list ✅ baseline
2 .olignore file (gitignore-style) ✅ additional layer
3 Respect existing .gitignore ⚠️ opt-in fallback only
4 Filter only on push, not on pull ❌ doesn't help — files exist locally regardless
5 Detect "looks like build output of an existing source" ❌ too magic
6 Document -output-directory=build/ 📝 doc-only mention

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions