texgit: Accessing Git Repositories from LaTeX

• Introduction
• Installation
• Files
• License
• Contact

1. Introduction

This package allows you to download and access files that reside in a git repository from within your LaTeX code. This can be used, for example, to include program code from an actual software in life repository in your LaTeX documents. It allows you to postprocess these files, e.g., to apply programs that remove comments or reformat code and then to include these postprocessed files. It furthermore allows you to execute programs (or scripts from git repositories) on your machine and include their output into your LaTeX documents. Finally, it also allows you to allocate files and pass them as parameters to the programs that you execute. With this, you could create PDF figures on the fly and then include them into your LaTeX documents.

This LaTeX package works \emph{only} in combination with the Python package texgit. To implement its functionality, it offers the following commands:

• \gitLoad{id}{repoURL}{pathInRepo}{postproc} loads a file pathInRepo from the git repository repoURL, optionally post-processes it by piping its contents into the standard input of a command postproc capturing its standard output.

• \gitFile{id} provides a local path to a file created this way. Using the \gitFile{id} macro, you can then include the file in LaTeX directly or load it as source code listing.

• \gitUrl{id} provides the URL to the original file in the git repository.

• \gitExec{id}{repoURL}{pathInRepo}{command} executes an arbitrary command command, either in the current directory or inside a directory pathInRepo of the git repository repoURL and fetches the standard output into a local file, the path to which is made available to the file again as macro \gitFile{id}.

• \gitArg{id}{prefix}{suffix} allocates an additional file, whose name will be composed of the optional prefix and suffix. Such files can be passed as arguments to \gitExec or \gitLoad\tbindex{gitLoad} by including (?id?) in their commands' argument list. This way, we can, for example, instruct a program to create a graphic and store it in a certain file that we can later load from \gitFile{id}.

• \gitIf{id}{ifDone}{ifNotDone} executes the code ifDone starting in the second pdflatex pass, i.e., after the Python texgit package has been applied to the aux file generated during the first pdflatex pass. During the first pdflatex pass and before the Python texgit package was applied, ifNotDone will be executed.

The functionality of the package is implemented by storing the git requests in the aux file of the project during the first pdflatex pass. The aux file is then processed by the Python package texgit which performs the actual git queries, program executions, stores the result in local files, and adds the resolved paths to the aux file. Thus, during the first pdflatex run, \gitFile and \gitUrl offer dummy results. During the second and later pass, after the Python program texgit has been applied to the aux file, they then provide the actual paths and URLs.

texgit is a LaTeX package that works in combination with a Python companion package for accessing files located in git repositories from within LaTeX. It works somewhat like BibTeX: In your LaTeX document, you first can define requests to load files from git repositories. During your first LaTeX compilation, these requests just evaluate to dummy results. They are, however, stored in that aux file of your project, say article.aux. Then you execute python3 -m texgit.run article (pretty much as you would execute bibtex article for building a bibliography). This Python package will then perform the actual git requests and update the aux file. In your next LaTeX pass, you can now access the contents of these files. This process is described in detail in the documentation.

2. Installation and Usage

1. Install the Python package texgit via pip install texgit
2. Download and copy texgit.sty from https://thomasweise.github.io/texgit_tex/texgit.sty into the folder of your LaTeX project or unpack texgit.tds.zip into your TeX tree¹ as described here or here.
3. Find the usage of the texgit LaTeX package described in texgit.pdf at https://thomasweise.github.io/texgit_tex/texgit.pdf.
4. Optionally: Read the documentation of the texgit Python companion at https://thomasweise.github.io/texgit_py.

To sum up things briefly: If you use the command \gitLoad{id}{myRepoUrl}{myFilePath}{myPostProcessor}, then our package will download the file at path myFilePath relative to the root of the git repository available at URL myRepoUrl. If myPostProcessor is left empty, the file is provided as-is at the path \gitFile{id}. If not left empty, myPostProcessor is executed as command in the shell, the downloaded file is piped into its stdin, and whatever the command writes to its stdout will become available as file pointed to by \gitFile{id}. You can then include this file or load it as code listing. Again, please read the documentation.

If your main document was stored as article.tex, you would build it using (at least) the three following steps:

1. pdflatex article
2. python3 -m texgit.run article
3. pdflatex article

3. Files

Below, we provide a list of files that may be interesting to look at.

1. texgit.dtx is the main source file of the package [html] | [raw]
2. texgit.ins is the installation script of the package [html] | [raw]
3. texgit.sty is the compiled style file [html] | [raw]
4. texgit.zip is a zipped version of our package in the format that can be submitted to https://ctan.org/upload.
5. texgit.tds.zip is a TDS packaged version of our package. In other words, it is an a .zip file that is ready to unzip into a user's TeX tree¹. This may be done as described here or here.
6. texgit.pdf is the documentation of the package [pdf]
7. LICENSE.html holds the license information for the package [html]
8. make.sh is the script with the build process [html] | [raw]
9. make_venv.sh creates a virtual environment with the required Python packages installed [html] | [raw] 10requirements.txt holds the Python requirements for using the package [html] | [txt] 11requirements-dev.txt holds the Python requirements for building the package [html] | [txt]

4. License

texgit is a tool for accessing files in git repositories from LaTeX.

Copyright (C) 2023&mash;2025 Thomas Weise (汤卫思教授)

Dr. Thomas Weise (see Contact) holds the copyright of this package. The package and its documentation are under the LaTeX Project Public License, version 1.3, which may be found online at http://www.latex-project.org/lppl.txt or at https://thomasweise.github.io/texgit_tex/LICENSE.html.

5. Contact

If you have any questions or suggestions, please contact Prof. Dr. Thomas Weise (汤卫思教授) of the Institute of Applied Optimization (应用优化研究所, IAO) of the School of Artificial Intelligence and Big Data (人工智能与大数据学院) at Hefei University (合肥大学) in Hefei, Anhui, China (中国安徽省合肥市) via email to [email protected] with CC to [email protected].