| Name | tartex JSON |
| Version |
0.8.0
JSON |
| download |
| home_page | None |
| Summary | Tar all files needed to re-compile your LaTeX project |
| upload_time | 2025-08-26 16:39:37 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
latex
latexmk
tar
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# tartex
[](https://pypi.org/project/tartex)
[](https://pypi.org/project/tartex)
[](https://github.com/pypa/hatch)
> 🧵 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](https://arxiv.org) and journal-ready bundles with zero clutter.
**Table of Contents**
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Typical Workflows](#typical-workflows)
- [License](#license)
- [Similar utilities](#similar-utilities)
## Features
- 📦 Produces compact, reproducible tarballs with a minimal list of files
- ✨ Compatible with [arXiv](https://arxiv.org) and most journal submission rules
- 💨 Fast: avoids re-compilation unless absolutely necessary or explicitly requested
- 📸 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
- 🖇️ Supports shell completions for bash, zsh, and fish
## Installation
> __Note__: If re-compilation of sources is required (no existing `.fls` file
> in source project), or is explicitly requested (`-F`/`--force-recompile`),
> you must have `latexmk` and `pdflatex`, 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.
### Using pipx
This is the easy way to install tagged releases.
```console
pipx install tartex
```
### From GitHub sources:
Compile using [hatch](https://hatch.pypa.io/latest/) to generate a wheel,
which may be then installed using `pipx` as follows:
```console
git clone https://github.com/badshah400/tartex.git
cd tartex
hatch build
pipx install ./dist/*.whl
```
## Usage
Supported OS: Potentially any POSIX-like, tested _only_ on Linux.
```console
usage: tartex [OPTIONS] FILENAME
Build a tarball including all source files needed to compile your LaTeX project
(version 0.8.0).
positional arguments:
FILENAME input file name [.tex|.fls] (with/without file ext.)
common options:
-h, --help show this help message and exit
-V, --version print tartex version and exit
-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 even if '.fls' found
--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 tartex
```
> __Note__: If the source dir of your LaTeX project already contains the `.fls`
> file previously generated by, say `latex -record` or `latexmk`, then `tartex`
> will directly use that file to determine which input files to include in the
> tarball. Otherwise, `tartex` will recompile your project using `latexmk` in a
> temp dir and use the `.fls` file generated there. To be precise, recompilation
> will invoke:
>
> ```console
> latexmk -f -<texmode> -cd -outdir=<tmpdir> -interaction=nonstopmode filename
> ```
>
> `texmode` is one of `pdf` or `ps` by default, as detemined from the contents of
> the source dir. It may be overridden by the `--latexmk-tex` option.
### Using with `--git-rev`
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.
- You don’t need to maintain a separate exclude list, the Git tree is the source
of truth.
- The tarball will exactly reflect the 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.gz` corresponding to a git rev short-ref of `a97023f`. If
the specified revision points to a tag, the tarfile is named `main-<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.
## Typical workflows
### Current Draft vs. Git Revision
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 tarball
two different snapshots to send to your collaborators, for example, to extract
and run [`latexdiff`](https://ctan.org/pkg/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` |
## License
`tartex` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
## Similar utilities
* [bundledoc](https://ctan.org/tex-archive/support/bundledoc) is a post-processor for the `snapshot` package that bundles together all the classes, packages and files needed to build a given LaTeX document.
Raw data
{
"_id": null,
"home_page": null,
"name": "tartex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "LaTeX, latexmk, tar",
"author": null,
"author_email": "Atri Bhattacharya <atrib@duck.com>",
"download_url": "https://files.pythonhosted.org/packages/5e/59/14261c11aaf2f5bc94ae718356ad993670e7f8d958e0635612d145e5b6ed/tartex-0.8.0.tar.gz",
"platform": null,
"description": "# tartex\n\n[](https://pypi.org/project/tartex)\n[](https://pypi.org/project/tartex)\n[](https://github.com/pypa/hatch)\n\n> \ud83e\uddf5 Minimal, reproducible tarballs for your LaTeX projects.\n\nTarTeX is a command-line utility to generate a tarball containing **all and\nonly** the source files needed to (re)compile your LaTeX project elsewhere.\n\nIt aims to produce [arXiv](https://arxiv.org) and journal-ready bundles with zero clutter.\n\n**Table of Contents**\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Typical Workflows](#typical-workflows)\n- [License](#license)\n- [Similar utilities](#similar-utilities)\n\n## Features\n\n- \ud83d\udce6 Produces compact, reproducible tarballs with a minimal list of files\n- \u2728 Compatible with [arXiv](https://arxiv.org) and most journal submission rules\n- \ud83d\udca8 Fast: avoids re-compilation unless absolutely necessary or explicitly requested\n- \ud83d\udcf8 Git integration: snapshot files into tarball directly from Git revision (`--git-rev`)\n- \ud83d\udd0d Auto-detects re-compilation processing mode (pdf/ps) from project\n- \ud83d\udd0f Leaves your LaTeX project directory unchanged\n- \ud83d\udd87\ufe0f Supports shell completions for bash, zsh, and fish\n\n## Installation\n\n> __Note__: If re-compilation of sources is required (no existing `.fls` file\n> in source project), or is explicitly requested (`-F`/`--force-recompile`),\n> you must have `latexmk` and `pdflatex`, as well as a full LaTeX env installed\n> to allow compilation of your LaTeX project. TarTeX does not include any\n> system-wide files, such as standard TeX style files, classes, etc. in the tar\n> file.\n\n### Using pipx\n\nThis is the easy way to install tagged releases.\n\n```console\npipx install tartex\n```\n\n### From GitHub sources:\n\nCompile using [hatch](https://hatch.pypa.io/latest/) to generate a wheel,\nwhich may be then installed using `pipx` as follows:\n\n```console\ngit clone https://github.com/badshah400/tartex.git\ncd tartex\nhatch build\npipx install ./dist/*.whl\n```\n\n## Usage\n\nSupported OS: Potentially any POSIX-like, tested _only_ on Linux.\n\n```console\nusage: tartex [OPTIONS] FILENAME\n\nBuild a tarball including all source files needed to compile your LaTeX project\n(version 0.8.0).\n\npositional arguments:\n FILENAME input file name [.tex|.fls] (with/without file ext.)\n\ncommon options:\n -h, --help show this help message and exit\n -V, --version print tartex version and exit\n -g, --git-rev=[REV] add git tree files at revision REV (default: HEAD)\n -l, --list, --dry-run print list of files to include and quit\n -o, --output=NAME[.EXT] output tar filename; 'EXT' sets re-compression mode,\n if one of 'bz2', 'gz' (default), or 'xz'\n --overwrite overwrite output tarball if necessary\n -p, --packages add used (La)TeX package names as json file\n -s, --summary print a summary at the end\n -v, --verbose increase log verbosity (-v, -vv, etc.)\n\noptions for additional file inclusion/exclusion in tar:\n -a, --add=PATTERNS include additional files matching glob PATTERN;\n separate multiple PATTERNs using commas\n -b, --bib find and add bib file to tarball\n --with-pdf add existing/generated final output PDF\n -x, --excl=PATTERNS exclude file names matching PATTERNS\n\noptions for latexmk processing (ignored for 'git-rev'):\n -F, --force-recompile force (La)TeX re-compile even if '.fls' found\n --latexmk-tex=TEXMODE force latexmk processing mode; TEXMODE is one of:\n dvi, lualatex, luatex, pdf, pdflua, ps, xdv, xelatex\n\noptions for tar re-compression (mutually conflicting); over-rides .EXT in '-o':\n -j, --bzip2 bzip2 (.bz2) re-compression\n -J, --xz lzma (.xz) re-compression\n -z, --gzip gzip (.gz) re-compression\n\noptions for shell TAB completion:\n --completion print shell completion guides for tartex\n --bash-completions install bash completions for tartex\n --fish-completions install fish completions for tartex\n --zsh-completions install zsh completions for tartex\n```\n\n> __Note__: If the source dir of your LaTeX project already contains the `.fls`\n> file previously generated by, say `latex -record` or `latexmk`, then `tartex`\n> will directly use that file to determine which input files to include in the\n> tarball. Otherwise, `tartex` will recompile your project using `latexmk` in a\n> temp dir and use the `.fls` file generated there. To be precise, recompilation\n> will invoke:\n>\n> ```console\n> latexmk -f -<texmode> -cd -outdir=<tmpdir> -interaction=nonstopmode filename\n> ```\n>\n> `texmode` is one of `pdf` or `ps` by default, as detemined from the contents of\n> the source dir. It may be overridden by the `--latexmk-tex` option.\n\n### Using with `--git-rev`\n\nWhen you specify a Git revision (via `--git-rev`), tartex _only_ includes files\nthat are tracked by Git at _that revision_. This means:\n\n- Files ignored by `.gitignore` (e.g. `*.aux`, `*.log`, build artifacts, temp files)\n are automatically excluded, since they are not tracked by Git.\n- No re-compilation of TeX sources.\n- You don\u2019t need to maintain a separate exclude list, the Git tree is the source\n of truth.\n- The tarball will exactly reflect the state of the project at the chosen revision,\n ensuring reproducibility.\n- Unless the output tar filename is explicitly specified by the user (via\n `-o`/`--output`), a git short-ref or tag-id will be appended to it. For example,\n `main-git.a97023f.tar.gz` corresponding to a git rev short-ref of `a97023f`. If\n the specified revision points to a tag, the tarfile is named `main-<TAG>.tar.gz`. \n\n> __Note__: When running without `--git-rev`, tartex applies its own LaTeX-aware\n> exclusion rules (e.g. skipping `.aux`, `.log`, `.fdb_latexmk`), to avoid including\n> transient build files in your archive.\n\n## Typical workflows\n\n### Current Draft vs. Git Revision\n\nTarTeX can be used in two different workflows, based on how you manage your\nLaTeX project. By default, TarTeX archives your project at the **current\ndraft** level as it appears in the source dir. This is useful when your files\nare not version controlled, or you simply want to tar (and send?) your source\nfiles at their current \u2014 potentially uncommitted \u2014 git state.\n\nIf, instead, your LaTeX project is version controlled using Git, and have a\nclean working tree, you can generate a tarball of files in your git tree as\nthey would have appeared at a specific revision. In this case, you can target a\n**Git revision** by specifying `--git-rev=[REV]` as an option to TarTeX. `REV`\ndefaults to `HEAD` if left unspecified. This will generate a tarball including\nall source files tracked by git (`git ls-tree -r`) and append a meaningful tag,\nindicative of the revision, to the final tar filename. This is useful, for\ninstance, when you are close to a version for submission and tagging your git\nrepository meaningfully; using TarTeX will produce tarballs with names like\n`foo-v0.9.tar.gz` and `bar-v1.0.tar.gz` for projects at git tags `v0.9` and\n`v1.0` respectively. Within the same project, this is also useful to tarball\ntwo different snapshots to send to your collaborators, for example, to extract\nand run [`latexdiff`](https://ctan.org/pkg/latexdiff) on them.\n\nThe table below highlights the key differences:\n\n| Feature | Current Draft (default) | Git Revision (`--git-rev`) |\n|-----------------------|---------------------------------------|---------------------------------------|\n| **Source of files** | Your working directory | A specific Git commit, tag, or branch |\n| **Uncommitted changes** | **Included** | **Ignored** |\n| **Reproducibility** | Depends on current state | Guaranteed (historical snapshot) |\n| **Typical use cases** | Submitting latest draft, sharing with collaborators | Packaging for journal submission, archiving published versions |\n| **Command example** | `tartex main.tex` \u2192 `main.tar.gz` | `tartex main.tex --git-rev v1.2` \u2192 `main-v1.2.tar.gz` |\n\n\n## License\n\n`tartex` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\n## Similar utilities\n\n* [bundledoc](https://ctan.org/tex-archive/support/bundledoc) is a post-processor for the `snapshot` package that bundles together all the classes, packages and files needed to build a given LaTeX document.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tar all files needed to re-compile your LaTeX project",
"version": "0.8.0",
"project_urls": {
"Documentation": "https://github.com/badshah400/tartex#readme",
"Issues": "https://github.com/badshah400/tartex/issues",
"Source": "https://github.com/badshah400/tartex"
},
"split_keywords": [
"latex",
" latexmk",
" tar"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cbf08cbbca54a3a7c9d480c1701a6dc6959ecbcd424364f94516dea5ec536400",
"md5": "fb64ca5a4e5b90b609d3bf36f0415a6d",
"sha256": "988c6261f85f9095fb09ae2be3b7bbda15d7627ebe3f56e772c3859103391a36"
},
"downloads": -1,
"filename": "tartex-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb64ca5a4e5b90b609d3bf36f0415a6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 25931,
"upload_time": "2025-08-26T16:39:38",
"upload_time_iso_8601": "2025-08-26T16:39:38.880547Z",
"url": "https://files.pythonhosted.org/packages/cb/f0/8cbbca54a3a7c9d480c1701a6dc6959ecbcd424364f94516dea5ec536400/tartex-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5e5914261c11aaf2f5bc94ae718356ad993670e7f8d958e0635612d145e5b6ed",
"md5": "26fef41fe3d0e22ec8af6cfb763a620d",
"sha256": "0e6c7f2f89b78d422f58093d3d81e08e2aae41be8d9c3182adb1f3e11e271552"
},
"downloads": -1,
"filename": "tartex-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "26fef41fe3d0e22ec8af6cfb763a620d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 150760,
"upload_time": "2025-08-26T16:39:37",
"upload_time_iso_8601": "2025-08-26T16:39:37.437367Z",
"url": "https://files.pythonhosted.org/packages/5e/59/14261c11aaf2f5bc94ae718356ad993670e7f8d958e0635612d145e5b6ed/tartex-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 16:39:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "badshah400",
"github_project": "tartex#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tartex"
}
