3. How to use the script

latexindent.pl ships as part of the TeXLive distribution for Linux and Mac users; latexindent.exe ships as part of the TeXLive for Windows users. These files are also available from github (“Home of Latexindent.pl” n.d.) should you wish to use them without a TeX distribution; in this case, you may like to read Section 12.2 which details how the path variable can be updated.

In what follows, we will always refer to latexindent.pl, but depending on your operating system and preference, you might substitute latexindent.exe or simply latexindent.

There are two ways to use latexindent.pl: from the command line, and using arara; we discuss these in Section 3.2 and Section 3.3 respectively. We will discuss how to change the settings and behaviour of the script in Section 5.

3.1. Requirements

3.1.1. Perl users

Perl users will need a few standard Perl modules – see Section 12.1 for details; in particular, note that a module installer helper script is shipped with latexindent.pl.

3.1.2. Windows users without perl

latexindent.pl ships with latexindent.exe for Windows users, so that you can use the script with or without a Perl distribution.

latexindent.exe is available from (“Home of Latexindent.pl” n.d.).

MiKTeX users on Windows may like to see (“How to Use Latexindent on Windows?” n.d.) for details of how to use latexindent.exe without a Perl installation.

3.1.3. Ubuntu Linux users without perl

latexindent.pl ships with latexindent-linux for Ubuntu Linux users, so that you can use the script with or without a Perl distribution.

latexindent-linux is available from (“Home of Latexindent.pl” n.d.).

3.1.4. macOS users without perl

latexindent.pl ships with latexindent-macos for macOS users, so that you can use the script with or without a Perl distribution.

latexindent-macOS is available from (“Home of Latexindent.pl” n.d.).

3.1.5. conda users

Users of conda should see the details given in Section 12.5.

3.1.6. docker users

Users of docker should see the details given in Section 12.6.

3.2. From the command line

latexindent.pl has a number of different switches/flags/options, which can be combined in any way that you like, either in short or long form as detailed below. latexindent.pl produces a .log file, indent.log, every time it is run; the name of the log file can be customised, but we will refer to the log file as indent.log throughout this document. There is a base of information that is written to indent.log, but other additional information will be written depending on which of the following options are used.

-v, –version

latexindent.pl -v
latexindent.pl --version

This will output only the version number to the terminal.

-vv, –vversion

latexindent.pl -vv
latexindent.pl --vversion

This will output verbose version details to the terminal, including the location of latexindent.pl and defaultSettings.yaml.

-h, –help

latexindent.pl -h
latexindent.pl --help

As above this will output a welcome message to the terminal, including the version number and available options.

latexindent.pl myfile.tex

This will operate on myfile.tex, but will simply output to your terminal; myfile.tex will not be changed by latexindent.pl in any way using this command.

You can instruct latexindent.pl to operate on multiple (batches) of files, for example

latexindent.pl myfile1.tex myfile2.tex

Full details are given in Section 12.3.

-w, –overwrite

latexindent.pl -w myfile.tex
latexindent.pl --overwrite myfile.tex
latexindent.pl myfile.tex --overwrite

This will overwrite myfile.tex, but it will make a copy of myfile.tex first. You can control the name of the extension (default is .bak), and how many different backups are made – more on this in Section 5, and in particular see backupExtension and onlyOneBackUp.

Note that if latexindent.pl can not create the backup, then it will exit without touching your original file; an error message will be given asking you to check the permissions of the backup file.

-wd, –overwriteIfDifferent

latexindent.pl -wd myfile.tex
latexindent.pl --overwriteIfDifferent myfile.tex
latexindent.pl myfile.tex --overwriteIfDifferent

This will overwrite myfile.tex but only if the indented text is different from the original. If the indented text is not different from the original, then myfile.tex will not be overwritten.

All other details from the -w switch are relevant here. If you call latexindent.pl with both the -wd and the -w switch, then the -w switch will be deactivated and the -wd switch takes priority.

-o=output.tex,–outputfile=output.tex

latexindent.pl -o=output.tex myfile.tex
latexindent.pl myfile.tex -o=output.tex
latexindent.pl --outputfile=output.tex myfile.tex
latexindent.pl --outputfile output.tex myfile.tex

This will indent myfile.tex and output it to output.tex, overwriting it (output.tex) if it already exists 1.

Note that if latexindent.pl is called with both the -w and -o switches, then -w will be ignored and -o will take priority (this seems safer than the other way round). The same is true for the -wd switch, and the -o switch takes priority over it.

Note that using -o as above is equivalent to using

latexindent.pl myfile.tex > output.tex

You can call the -o switch with the name of the output file without an extension; in this case, latexindent.pl will use the extension from the original file. For example, the following two calls to latexindent.pl are equivalent:

latexindent.pl myfile.tex -o=output
latexindent.pl myfile.tex -o=output.tex

You can call the -o switch using a + symbol at the beginning; this will concatenate the name of the input file and the text given to the -o switch. For example, the following two calls to latexindent.pl are equivalent:

latexindent.pl myfile.tex -o=+new
latexindent.pl myfile.tex -o=myfilenew.tex

You can call the -o switch using a ++ symbol at the end of the name of your output file; this tells latexindent.pl to search successively for the name of your output file concatenated with \(0, 1, \ldots\) while the name of the output file exists. For example,

latexindent.pl myfile.tex -o=output++

tells latexindent.pl to output to output0.tex, but if it exists then output to output1.tex, and so on.

Calling latexindent.pl with simply

latexindent.pl myfile.tex -o=++

tells it to output to myfile0.tex, but if it exists then output to myfile1.tex and so on.

The + and ++ feature of the -o switch can be combined; for example, calling

latexindent.pl myfile.tex -o=+out++

tells latexindent.pl to output to myfileout0.tex, but if it exists, then try myfileout1.tex, and so on.

There is no need to specify a file extension when using the ++ feature, but if you wish to, then you should include it after the ++ symbols, for example

latexindent.pl myfile.tex -o=+out++.tex

See Section 12.12 for details of how the interface has changed from Version 2.2 to Version 3.0 for this flag. .. describe:: -s, –silent

latexindent.pl -s myfile.tex
latexindent.pl myfile.tex -s

Silent mode: no output will be given to the terminal.

-t, –trace

latexindent.pl -t myfile.tex
latexindent.pl myfile.tex -t

Tracing mode: verbose output will be given to indent.log. This is useful if latexindent.pl has made a mistake and you’re trying to find out where and why. You might also be interested in learning about latexindent.pl’s thought process – if so, this switch is for you, although it should be noted that, especially for large files, this does affect performance of the script.

-tt, –ttrace

latexindent.pl -tt myfile.tex
latexindent.pl myfile.tex -tt

More detailed tracing mode: this option gives more details to indent.log than the standard trace option (note that, even more so than with -t, especially for large files, performance of the script will be affected).

-l, –local[=myyaml.yaml,other.yaml,...]

latexindent.pl -l myfile.tex
latexindent.pl -l=myyaml.yaml myfile.tex
latexindent.pl -l myyaml.yaml myfile.tex
latexindent.pl -l first.yaml,second.yaml,third.yaml myfile.tex
latexindent.pl -l=first.yaml,second.yaml,third.yaml myfile.tex
latexindent.pl myfile.tex -l=first.yaml,second.yaml,third.yaml

latexindent.pl will always load defaultSettings.yaml (rhymes with camel) and if it is called with the -l switch and it finds localSettings.yaml in the same directory as myfile.tex, then, if not found, it looks for localSettings.yaml (and friends, see Section 4.2) in the current working directory, then these settings will be added to the indentation scheme. Information will be given in indent.log on the success or failure of loading localSettings.yaml.

The -l flag can take an optional parameter which details the name (or names separated by commas) of a YAML file(s) that resides in the same directory as myfile.tex; you can use this option if you would like to load a settings file in the current working directory that is not called localSettings.yaml. In fact, you can specify both relative and absolute paths for your YAML files; for example

latexindent.pl -l=../../myyaml.yaml myfile.tex
latexindent.pl -l=/home/cmhughes/Desktop/myyaml.yaml myfile.tex
latexindent.pl -l=C:\Users\cmhughes\Desktop\myyaml.yaml myfile.tex

You will find a lot of other explicit demonstrations of how to use the -l switch throughout this documentation,

You can call the -l switch with a ‘+’ symbol either before or after another YAML file; for example:

latexindent.pl -l=+myyaml.yaml myfile.tex
latexindent.pl -l "+ myyaml.yaml" myfile.tex
latexindent.pl -l=myyaml.yaml+  myfile.tex

which translate, respectively, to

latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex
latexindent.pl -l=localSettings.yaml,myyaml.yaml myfile.tex
latexindent.pl -l=myyaml.yaml,localSettings.yaml myfile.tex

Note that the following is not allowed:

latexindent.pl -l+myyaml.yaml myfile.tex

and

latexindent.pl -l + myyaml.yaml myfile.tex

will only load localSettings.yaml, and myyaml.yaml will be ignored. If you wish to use spaces between any of the YAML settings, then you must wrap the entire list of YAML files in quotes, as demonstrated above.

You may also choose to omit the yaml extension, such as

latexindent.pl -l=localSettings,myyaml myfile.tex

-y, –yaml=yaml settings

latexindent.pl myfile.tex -y="defaultIndent: ' '"
latexindent.pl myfile.tex -y="defaultIndent: ' ',maximumIndentation:' '"
latexindent.pl myfile.tex -y="indentRules: one: '\t\t\t\t'"
latexindent.pl myfile.tex -y='modifyLineBreaks:environments:EndStartsOnOwnLine:3' -m
latexindent.pl myfile.tex -y='modifyLineBreaks:environments:one:EndStartsOnOwnLine:3' -m

You can specify YAML settings from the command line using the -y or –yaml switch; sample demonstrations are given above. Note, in particular, that multiple settings can be specified by separating them via commas. There is a further option to use a ; to separate fields, which is demonstrated in Section 4.3.

Any settings specified via this switch will be loaded after any specified using the -l switch. This is discussed further in Section 4.4. .. describe:: -d, –onlydefault

latexindent.pl -d myfile.tex

Only defaultSettings.yaml: you might like to read Section 5 before using this switch. By default, latexindent.pl will always search for indentconfig.yaml or .indentconfig.yaml in your home directory. If you would prefer it not to do so then (instead of deleting or renaming indentconfig.yaml or .indentconfig.yaml) you can simply call the script with the -d switch; note that this will also tell the script to ignore localSettings.yaml even if it has been called with the -l switch; latexindent.pl will also ignore any settings specified from the -y switch.

-c, –cruft=<directory>

latexindent.pl -c=/path/to/directory/ myfile.tex

If you wish to have backup files and indent.log written to a directory other than the current working directory, then you can send these ‘cruft’ files to another directory. Note the use of a trailing forward slash.

-g, –logfile=<name of log file>

latexindent.pl -g=other.log myfile.tex
latexindent.pl -g other.log myfile.tex
latexindent.pl --logfile other.log myfile.tex
latexindent.pl myfile.tex -g other.log

By default, latexindent.pl reports information to indent.log, but if you wish to change the name of this file, simply call the script with your chosen name after the -g switch as demonstrated above.

If latexindent.pl can not open the log file that you specify, then the script will operate, and no log file will be produced; this might be helpful to users who wish to specify the following, for example

latexindent.pl -g /dev/null myfile.tex

-sl, –screenlog

latexindent.pl -sl myfile.tex
latexindent.pl -screenlog myfile.tex

Using this option tells latexindent.pl to output the log file to the screen, as well as to your chosen log file.

-m, –modifylinebreaks

latexindent.pl -m myfile.tex
latexindent.pl -modifylinebreaks myfile.tex

One of the most exciting developments in Version 3.0 is the ability to modify line breaks; for full details see Section 6

latexindent.pl can also be called on a file without the file extension, for example

latexindent.pl myfile

and in which case, you can specify the order in which extensions are searched for; see Listing 52 for full details. .. describe:: STDIN

cat myfile.tex | latexindent.pl
cat myfile.tex | latexindent.pl -

latexindent.pl will allow input from STDIN, which means that you can pipe output from other commands directly into the script. For example assuming that you have content in myfile.tex, then the above command will output the results of operating upon myfile.tex.

If you wish to use this feature with your own local settings, via the -l switch, then you should finish your call to latexindent.pl with a - sign:

cat myfile.tex | latexindent.pl -l=mysettings.yaml -

Similarly, if you simply type latexindent.pl at the command line, then it will expect (STDIN) input from the command line.

latexindent.pl

Once you have finished typing your input, you can press

CTRL+D on Linux
CTRL+Z followed by ENTER on Windows

to signify that your input has finished. Thanks to ((xu-cheng) 2018) for an update to this feature. .. describe:: -r, –replacement

latexindent.pl -r myfile.tex
latexindent.pl -replacement myfile.tex

You can call latexindent.pl with the -r switch to instruct it to perform replacements/substitutions on your file; full details and examples are given in Section 7.

-rv, –replacementrespectverb

latexindent.pl -rv myfile.tex
latexindent.pl -replacementrespectverb myfile.tex

You can instruct latexindent.pl to perform replacements/substitutions by using the -rv switch, but will respect verbatim code blocks; full details and examples are given in Section 7.

-rr, –onlyreplacement

latexindent.pl -rr myfile.tex
latexindent.pl -onlyreplacement myfile.tex

You can instruct latexindent.pl to skip all of its other indentation operations and only perform replacements/substitutions by using the -rr switch; full details and examples are given in Section 7.

-k, –check

latexindent.pl -k myfile.tex
latexindent.pl -check myfile.tex

You can instruct latexindent.pl to check if the text after indentation matches that given in the original file.

The exit code

of latexindent.pl is 0 by default. If you use the -k switch then

if the text after indentation matches that given in the original file, then the exit code is 0;
if the text after indentation does not match that given in the original file, then the exit code is 1.

The value of the exit code may be important to those wishing to, for example, check the status of the indentation in continuous integration tools such as GitHub Actions. Full details of the exit codes of latexindent.pl are given in Table 1.

A simple diff will be given in indent.log.

-kv, –checkv

latexindent.pl -kv myfile.tex
latexindent.pl -checkv myfile.tex

The check verbose switch is exactly the same as the -k switch, except that it is verbose, and it will output the (simple) diff to the terminal, as well as to indent.log.

-n, –lines=MIN-MAX

latexindent.pl -n 5-8 myfile.tex
latexindent.pl -lines 5-8 myfile.tex

The lines switch instructs latexindent.pl to operate only on specific line ranges within myfile.tex.

Complete demonstrations are given in Section 8.

–GCString

latexindent.pl --GCString myfile.tex

instructs latexindent.pl to load the Unicode::GCString module. This should only be necessary if you find that the alignment at ampersand routine (described in Section 5.5) does not work for your language. Further details are given in Section 12.1.6.

3.3. From arara

Using latexindent.pl from the command line is fine for some folks, but others may find it easier to use from arara; you can find the arara rule for latexindent.pl and its associated documentation at (Cereda 2013).

3.4. Summary of exit codes

Assuming that you call latexindent.pl on myfile.tex

latexindent.pl myfile.tex

then latexindent.pl can exit with the exit codes given in Table 1.

Table 1 Exit codes for `latexindent.pl`
exit code	indentation	status
0	yes	success; if `-k` or `-kv` active, indented text matches original
0	no	success; if `-version`, `-vversion` or `-help`, no indentation performed
1	yes	success, and `-k` or `-kv` active; indented text different from original
2	no	failure, `defaultSettings.yaml` could not be read
3	no	failure, myfile.tex not found
4	no	failure, myfile.tex exists but cannot be read
5	no	failure, `-w` active, and back-up file cannot be written
6	no	failure, `-c` active, and cruft directory does not exist

Cereda, Paulo. 2013. “Arara Rule, Indent.yaml.” May 23, 2013. https://github.com/islandoftex/arara/blob/master/rules/arara-rule-indent.yaml.

“Home of Latexindent.pl.” n.d. Accessed January 23, 2017. https://github.com/cmhughes/latexindent.pl.

“How to Use Latexindent on Windows?” n.d. Accessed January 8, 2022. https://tex.stackexchange.com/questions/577250/how-to-use-latexindent-on-windows.

(xu-cheng), Cheng Xu. 2018. “Always Output Log/Help Text to Stderr.” July 13, 2018. https://github.com/cmhughes/latexindent.pl/pull/121.

1: Users of version 2.* should note the subtle change in syntax