🧵 Minimal, reproducible tarballs for your LaTeX projects.
TarTeX is a command-line utility to generate a tarball containing all and only the source files needed to (re)compile your LaTeX project elsewhere.
It aims to produce arXiv and journal-ready bundles with zero clutter.
Table of Contents
- 📦 Produces compact, reproducible tarballs with a minimal list of files
- ✨ Compatible with arXiv and most journal submission rules
- 💨 Fast: caches list of dependencies and avoids re-compilation unless necessary or forced
- 📸 Git integration: snapshot files into tarball directly from Git revision (
--git-rev) - 🔍 Auto-detects re-compilation processing mode (pdf/ps) from project
- 🔏 Leaves your LaTeX project directory unchanged
- 🕵️ Optional check to ensure final tarball contains all necessary files
- 🖇️ Supports shell completions for bash, zsh, and fish
Note: If re-compilation of sources is required (cache file not generated or accessible), or is explicitly requested (
-F/--force-recompile), you must havelatexmkandpdflatex, as well as a full LaTeX env installed to allow compilation of your LaTeX project. TarTeX does not include any system-wide files, such as standard TeX style files, classes, etc. in the tar file. This is also required for the check options (--check/--only-check).
This is the easy way to install tagged releases.
pipx install tartexCompile using hatch to generate a wheel,
which may be then installed using pipx as follows:
git clone https://github.com/badshah400/tartex.git
cd tartex
hatch build
pipx install ./dist/*.whlSupported OS: Potentially cross-platform, but tested only on Linux for now.
usage: tartex [OPTIONS] FILENAME
Build a tarball including all source files needed to compile your LaTeX project
(version 0.11.1).
positional arguments:
FILENAME input file name [.fls|.tex] (with/without extension)
common options:
-h, --help show this help message and exit
-V, --version print tartex version and exit
-c, --check Check if tarball has all files needed for compiling
-C, --only-check Only check and print detailed report; no tarball
-g, --git-rev=[REV] add git tree files at revision REV (default: HEAD)
-l, --list, --dry-run print list of files to include and quit
-o, --output=NAME[.EXT] output tar filename; 'EXT' sets re-compression mode,
if one of 'bz2', 'gz' (default), or 'xz'
--overwrite overwrite output tarball if necessary
-p, --packages add used (La)TeX package names as json file
-s, --summary print a summary at the end
-v, --verbose increase log verbosity (-v, -vv, etc.)
options for additional file inclusion/exclusion in tar:
-a, --add="PATTERNs" include additional files matching glob PATTERN;
separate multiple PATTERNs using commas
-b, --bib find and add bib file to tarball
--with-pdf add existing/generated final output PDF
-x, --excl="PATTERNs" exclude file names matching PATTERNS
options for latexmk processing (ignored for 'git-rev'):
-F, --force-recompile force (La)TeX re-compile; cache use/update disabled
--latexmk-tex=TEXMODE force latexmk processing mode; TEXMODE is one of:
dvi, lualatex, luatex, pdf, pdflua, ps, xdv, xelatex
options for tar re-compression (mutually conflicting); over-rides .EXT in '-o':
-j, --bzip2 bzip2 (.bz2) re-compression
-J, --xz lzma (.xz) re-compression
-z, --gzip gzip (.gz) re-compression
options for shell TAB completion:
--completion print shell completion guides for tartex
--bash-completions install bash completions for tartex
--fish-completions install fish completions for tartex
--zsh-completions install zsh completions for tartexNote: If the main input file specified on the cmdline has an extension '.fls', previously generated by, say
latex -recordorlatexmk, thentartexwill directly use that to determine which input files to include in the tarball. Otherwise,tartexwill recompile your project usinglatexmkin a temporary dir and use the.flsfile generated there to determine necessary dependencies. To be precise, recompilation will invoke:latexmk -f -<texmode> -cd -outdir=<tmpdir> -interaction=nonstopmode filename
texmodeis one ofpsby default, as detemined from the contents of the source dir. It may be overridden by the--latexmk-texoption.
When you specify a Git revision (via --git-rev), tartex only includes files
that are tracked by Git at that revision. This means:
- Files ignored by
.gitignore(e.g.*.aux,*.log, build artifacts, temp files) are automatically excluded, since they are not tracked by Git. - No re-compilation of TeX sources (unless using one of the
checkoptions). - No checking or updating of cache file, otherwise used to track input file changes.
- No need to maintain a separate exclude list.
- Output tarball reflects the exact state of the project at the chosen revision, ensuring reproducibility.
- Unless the output tar filename is explicitly specified by the user (via
-o/--output), a git short-ref or tag-id will be appended to it. For example,main-git.a97023f.tar.gzcorresponding to a git rev short-ref ofa97023f. If the specified revision points to a tag, the tarfile is namedmain-<TAG>.tar.gz.
Note: When running without
--git-rev, tartex applies its own LaTeX-aware exclusion rules (e.g. skipping.aux,.log,.fdb_latexmk), to avoid including transient build files in your archive.
TarTeX can be used in two different workflows, based on how you manage your LaTeX project. By default, TarTeX archives your project at the current draft level as it appears in the source dir. This is useful when your files are not version controlled, or you simply want to tar (and send?) your source files at their current — potentially uncommitted — git state.
If, instead, your LaTeX project is version controlled using Git, and have a
clean working tree, you can generate a tarball of files in your git tree as
they would have appeared at a specific revision. In this case, you can target a
Git revision by specifying --git-rev=[REV] as an option to TarTeX. REV
defaults to HEAD if left unspecified. This will generate a tarball including
all source files tracked by git (git ls-tree -r) and append a meaningful tag,
indicative of the revision, to the final tar filename. This is useful, for
instance, when you are close to a version for submission and tagging your git
repository meaningfully; using TarTeX will produce tarballs with names like
foo-v0.9.tar.gz and bar-v1.0.tar.gz for projects at git tags v0.9 and
v1.0 respectively. Within the same project, this is also useful to tar
two different snapshots to send to your collaborators, for instance, to extract
and run latexdiff on them.
The table below highlights the key differences:
| Feature | Current Draft (default) | Git Revision (--git-rev) |
|---|---|---|
| Source of files | Your working directory | A specific Git commit, tag, or branch |
| Uncommitted changes | Included | Ignored |
| Reproducibility | Depends on current state | Guaranteed (historical snapshot) |
| Typical use cases | Submitting latest draft, sharing with collaborators | Packaging for journal submission, archiving published versions |
| Command example | tartex main.tex → main.tar.gz |
tartex main.tex --git-rev v1.2 → main-v1.2.tar.gz |
tartex is distributed under the terms of the MIT license.
nautilus-tartexis an extension for the GNOME Files app nautilus that adds a context menu item for one-click archiving of LaTeX project files using TarTeX.
- bundledoc is a
post-processor for the
snapshotpackage that bundles together all the classes, packages and files needed to build a given LaTeX document.
Some features, like the --git-rev option — but no actual code itself —
were motivated by discussions with Gemini AI.