alexrutar/tpr

A command-line LaTeX templating tool.

LaTeX Project Manager

TexProject is a LaTeX project manager that performs basic project templating and also includes other utilities for compiling and exporting your files in a well-defined way.

Jump to:

• Installation
• Dependencies
• Basic usage
• Advanced features

Installation

If you have something like fisher, you can

fisher install alexrutar/tpr

Otherwise, the function is in functions/tpr.fish and the completions are in completions/tpr.fish and you can just copy them to the relevant folders.

Dependencies

In order to use tpr, you need a few dependencies.

1. A working LaTeX distribution which supports latexmk (such as TeX Live).
2. git, for managing version control.
3. fd, for basic file system management.

If you want to use the tpr init and tpr template commands, you need

4. copier, for template management.

If you want to use the tpr remote command, you need:

5. The github cli, for managing remote repositories.
6. yq, for reading configuration files.

If you want to use the tpr archive --bare command, you may want the following additional dependency.

7. arxiv_latex_cleaner, for removal of comments and additional cleaning of export folder.

Visit the linked pages for precise installation instructions.

Basic usage

Initialization

In order to use tpr, we first need to install some templates. We can use this preprint template. Simply run

tpr template install preprint https://github.com/rutar-academic/template-preprint

This installs the template located at the URL https://github.com/rutar-academic/template-preprint under the name preprint. You can install templates from any valid git URL or a local git repository.

List available templates with tpr template list. Templates are installed in the directory $XDG_DATA_HOME/tpr/templates.

Now, create a new directory, change to it, and initialize:

mkdir my-project
cd my-project
tpr init preprint

This will copy a number of files to the current directory and initialize a git repository.

Compilation and exports

To build a PDF file from the project, run

tpr compile out.pdf

This generates a file out.pdf in the current directory by compiling the file <main>.tex specified by <main>.tex.latexmain. The compilation may take a while since it ignores any intermediate files already in the folder.

To export the project, run

tpr archive out.tar.gz

to create an archive file out.tar.gz. You can include additional files in the archive with -I and strip unnecessary comments and unneeded files with --bare. For example, to prepare files for submission to arXiv, one might run

tpr archive --bare -I bbl arxiv.tar.gz

More help

Run

tpr --help

or

tpr $subcommand --help

for more information.

Advanced features

Compiling and exporting specific commits

Some commands, such as tpr compile or tpr archive, take an optional COMMIT argument. This can be any git tree-ish reference, as accepted by git archive. For instance, if you have a tag v0.1, you can run

tpr archive out.tar.gz v0.1

to create an export using the v0.1 tag.

Creating diff files

It is often useful to visualize changes between two versions of a .tex file. A convenient tool for doing this is the latexdiff script. The tpr diff tool provides a wrapper around latexdiff to automatically generate the diff file and compile it. For example

tpr diff diff.pdf HEAD~3

creates a file diff.pdf showing the changes made between HEAD~3 and HEAD. Note that the file diff.pdf is compiled against the project files in HEAD. This may cause compilation issues if there are substantial changes in other project files.

Remote repository management

You can create remote repositories on GitHub using the tpr remote subcommand. Simply run with

tpr remote username/repo

to create a private GitHub repository at https://github.com/username/repo.

Note that tpr remote reads some default settings from $XDG_CONFIG_HOME/tpr/config.toml.

Managing templates

You can update all existing templates with

tpr template update

Uninstall template $name with

tpr template uninstall $name

Writing your own templates

Templates for tpr are managed using copier. A valid template is any copier template that contains a file at the root <main>.tex as well as an empty file <main>.tex.latexmain. Of course, <main> can be anything you would like: the .latexmain file is used to determine the main TeX file in the current directory.

You can view my preprint template for some quick-start information, and otherwise read the copier documentation for more detail.

It is recommended that you include a reasonable .gitignore file which includes some common ignores for .tex files. The GitHub TeX Gitignore is a good starting point.