Preamble
The following options determine the visual markup style by adding the appropriate command definitions to
the preamble. See the end of this section for a description of available styles.
--type=markupstyle or -tmarkupstyle
Add code to preamble for selected markup style. This option defines "\DIFadd" and "\DIFdel" commands.
Available styles:
"UNDERLINE CTRADITIONAL TRADITIONAL CFONT FONTSTRIKE INVISIBLE CHANGEBAR CCHANGEBAR CULINECHBAR
CFONTCHBAR BOLD PDFCOMMENT"
[ Default: "UNDERLINE" ]
--subtype=markstyle or -smarkstyle
Add code to preamble for selected style for bracketing commands (e.g. to mark changes in margin).
This option defines "\DIFaddbegin", "\DIFaddend", "\DIFdelbegin" and "\DIFdelend" commands.
Available styles: "SAFE MARGIN COLOR DVIPSCOL ZLABEL ONLYCHANGEDPAGE (LABEL)*"
[ Default: "SAFE" ] * Subtype "LABEL" is deprecated
--floattype=markstyle or -fmarkstyle
Add code to preamble for selected style which replace standard marking and markup commands within
floats (e.g., marginal remarks cause an error within floats so marginal marking can be disabled
thus). This option defines all "\DIF...FL" commands. Available styles: "FLOATSAFE TRADITIONALSAFE
IDENTICAL"
[ Default: "FLOATSAFE" ]
--encoding=enc or -eenc
Specify encoding of old.tex and new.tex. Typical encodings are "ascii", "utf8", "latin1", "latin9".
A list of available encodings can be obtained by executing
"perl -MEncode -e 'print join ("\n",Encode-"encodings( ":all" )) ;' >
If this option is used, then old.tex, new.tex are only opened once. [Default encoding is utf8 unless
the first few lines of the preamble contain an invocation "\usepackage[..]{inputenc}" in which case
the encoding chosen by this command is asssumed. Note that ASCII (standard latex) is a subset of
utf8]
--preamble=file or -pfile
Insert file at end of preamble instead of generating preamble. The preamble must define the
following commands "\DIFaddbegin, \DIFaddend, \DIFadd{..}, \DIFdelbegin,\DIFdelend,\DIFdel{..}," and
varieties for use within floats "\DIFaddbeginFL, \DIFaddendFL, \DIFaddFL{..}, \DIFdelbeginFL,
\DIFdelendFL, \DIFdelFL{..}" (If this option is set -t, -s, and -f options are ignored.)
--packages=pkg1,pkg2,..
Tell latexdiff that .tex file is processed with the packages in list loaded. This is normally not
necessary if the .tex file includes the preamble, as the preamble is automatically scanned for
"\usepackage" commands. Use of the --packages option disables automatic scanning, so if for any
reason package specific parsing needs to be switched off, use --packages=none. The following
packages trigger special behaviour:
"amsmath"
Configuration variable MATHARRREPL is set to "align*" (Default: "eqnarray*"). (Note that many
of the amsmath array environments are already recognised by default as such)
"endfloat"
Ensure that "\begin{figure}" and "\end{figure}" always appear by themselves on a line.
"hyperref"
Change name of "\DIFadd" and "\DIFdel" commands to "\DIFaddtex" and "\DIFdeltex" and define
new "\DIFadd" and "\DIFdel" commands, which provide a wrapper for these commands, using them
for the text but not for the link defining command (where any markup would cause errors).
"apacite", "biblatex"
Redefine the commands recognised as citation commands.
"siunitx"
Treat "\SI" as equivalent to citation commands (i.e. protect with "\mbox" if markup style
uses ulem package.
"cleveref"
Treat "\cref,\Cref", etc as equivalent to citation commands (i.e. protect with "\mbox" if
markup style uses ulem package.
"glossaries"
Define most of the glossaries commands as safe, protecting them with \mbox'es where needed
"mhchem"
Treat "\ce" as a safe command, i.e. it will be highlighted (note that "\cee" will not be
highlighted in equations as this leads to processing errors)
"chemformula" or "chemmacros"
Treat "\ch" as a safe command outside equations, i.e. it will be highlighted (note that "\ch"
will not be highlighted in equations as this leads to processing errors)
[ Default: scan the preamble for "\usepackage" commands to determine
loaded packages. ]
--show-preamble
Print generated or included preamble commands to stdout.
Configuration--exclude-safecmd=exclude-file or -Aexclude-file or --exclude-safecmd="cmd1,cmd2,..."--replace-safecmd=replace-file--append-safecmd=append-file or -aappend-file or --append-safecmd="cmd1,cmd2,..."
Exclude from, replace or append to the list of regular expressions (RegEx) matching commands which
are safe to use within the scope of a "\DIFadd" or "\DIFdel" command. The file must contain one
Perl-RegEx per line (Comment lines beginning with # or % are ignored). Note that the RegEx needs to
match the whole of the token, i.e., /^regex$/ is implied and that the initial "\" of the command is
not included. The --exclude-safecmd and --append-safecmd options can be combined with the
---replace-safecmd option and can be used repeatedly to add cumulatively to the lists.
--exclude-safecmd and --append-safecmd can also take a comma separated list as input. If a comma for
one of the regex is required, escape it thus "\,". In most cases it will be necessary to protect the
comma-separated list from the shell by putting it in quotation marks.
--exclude-textcmd=exclude-file or -Xexclude-file or --exclude-textcmd="cmd1,cmd2,..."--replace-textcmd=replace-file--append-textcmd=append-file or -xappend-file or --append-textcmd="cmd1,cmd2,..."
Exclude from, replace or append to the list of regular expressions matching commands whose last
argument is text. See entry for --exclude-safecmd directly above for further details.
--replace-context1cmd=replace-file--append-context1cmd=append-file or
--append-context1cmd="cmd1,cmd2,..."
Replace or append to the list of regex matching commands whose last argument is text but which
require a particular context to work, e.g. "\caption" will only work within a figure or table. These
commands behave like text commands, except when they occur in a deleted section, when they are
disabled, but their argument is shown as deleted text.
--replace-context2cmd=replace-file--append-context2cmd=append-file or
--append-context2cmd="cmd1,cmd2,..."
As corresponding commands for context1. The only difference is that context2 commands are completely
disabled in deleted sections, including their arguments.
context2 commands are also the only commands in the preamble, whose argument will be processed in
word-by-word mode (which only works, if they occur no more than once in the preamble). The algorithm
currently cannot cope with repeated context2 commands in the preamble, as they occur e.g. for the
"\author" argument in some journal styles (not in the standard styles, though If such a repetition is
detected, the whole preamble will be processed in line-by-line mode. In such a case, use
"--replace-context2cmd" option to just select the commands, which should be processed and are not
used repeatedly in the preamble.
--exclude-mboxsafecmd=exclude-file or --exclude-mboxsafecmd="cmd1,cmd2,..."--append-mboxsafecmd=append-file or --append-mboxsafecmd="cmd1,cmd2,..."
Define safe commands, which additionally need to be protected by encapsulating in an "\mbox{..}".
This is sometimes needed to get around incompatibilities between external packages and the ulem
package, which is used for highlighting in the default style UNDERLINE as well as CULINECHBAR
CFONTSTRIKE
--configvar1=val1,var2=val2,... or -cvar1=val1,..-cconfigfile
Set configuration variables. The option can be repeated to set different variables (as an
alternative to the comma-separated list). Available variables (see below for further explanations):
"ARRENV" (RegEx)
"COUNTERCMD" (RegEx)
"CUSTODIFCMD" (RegEx)
"FLOATENV" (RegEx)
"ITEMCMD" (RegEx)
"LISTENV" (RegEx)
"MATHARRENV" (RegEx)
"MATHARRREPL" (String)
"MATHENV" (RegEx)
"MATHREPL" (String)
"MINWORDSBLOCK" (Integer)
"PICTUREENV" (RegEx)
"SCALEDELGRAPHICS" (Float)
--add-to-configvarenv1=pattern1,varenv2=pattern2,...
For configuration variables, which are a regular expression (essentially those ending in ENV,
COUNTERCMD and CUSTOMDIFCMD, see list above) this option provides an alternative way to modify the
configuration variables. Instead of setting the complete pattern, with this option it is possible to
add an alternative pattern. "varenv" must be one of the variables listed above that take a regular
expression as argument, and pattern is any regular expression (which might need to be protected from
the shell by quotation). Several patterns can be added at once by using semi-colons to separate them,
e.g. "--add-to-config "LISTENV=myitemize;myenumerate,COUNTERCMD=endnote""
--show-safecmd
Print list of RegEx matching and excluding safe commands.
--show-textcmd
Print list of RegEx matching and excluding commands with text argument.
--show-config
Show values of configuration variables.
--show-all
Combine all --show commands.
NB For all --show commands, no "old.tex" or "new.tex" file needs to be specified, and no differencing
takes place.
Otherconfigurationoptions:--allow-spaces
Allow spaces between bracketed or braced arguments to commands. Note that this option might have
undesirable side effects (unrelated scope might get lumpeded with preceding commands) so should only
be used if the default produces erroneous results. (Default requires arguments to directly follow
each other without intervening spaces).
--math-markup=level
Determine granularity of markup in displayed math environments: Possible values for level are (both
numerical and text labels are acceptable):
"off" or 0: suppress markup for math environments. Deleted equations will not appear in diff file.
This mode can be used if all the other modes cause invalid latex code.
"whole" or 1: Differencing on the level of whole equations. Even trivial changes to equations cause
the whole equation to be marked changed. This mode can be used if processing in coarse or fine mode
results in invalid latex code.
"coarse" or 2: Detect changes within equations marked up with a coarse granularity; changes in
equation type (e.g.displaymath to equation) appear as a change to the complete equation. This mode is
recommended for situations where the content and order of some equations are still being changed.
[Default]
"fine" or 3: Detect small change in equations and mark up at fine granularity. This mode is most
suitable, if only minor changes to equations are expected, e.g. correction of typos.
--graphics-markup=level
Change highlight style for graphics embedded with C<\includegraphics> commands.
Possible values for level:
"none", "off" or 0: no highlighting for figures
"new-only" or 1: surround newly added or changed figures with a blue frame [Default if graphicx
package loaded]
"both" or 2: highlight new figures with a blue frame and show deleted figures at reduced scale,
and crossed out with a red diagonal cross. Use configuration variable SCALEDELGRAPHICS to set size of
deleted figures.
Note that changes to the optional parameters will make the figure appear as changed to latexdiff, and
this figure will thus be highlighted.
In some circumstances "Misplaced \noalign" error can occur if there are certain types of changes in
tables. In this case please use "--graphics-markup=none" as a work-around.
--disable-citation-markup or --disable-auto-mbox
Suppress citation markup and markup of other vulnerable commands in styles using ulem
(UNDERLINE,FONTSTRIKE, CULINECHBAR) (the two options are identical and are simply aliases)
--enable-citation-markup or --enforce-auto-mbox
Protect citation commands and other vulnerable commands in changed sections with "\mbox" command,
i.e. use default behaviour for ulem package for other packages (the two options are identical and are
simply aliases)
Miscellaneous--verbose or -V
Output various status information to stderr during processing. Default is to work silently.
--driver=type
Choose driver for changebar package (only relevant for styles using
changebar: CCHANGEBAR CFONTCHBAR CULINECHBAR CHANGEBAR). Possible drivers are listed in changebar
manual, e.g. pdftex,dvips,dvitops
[Default: pdftex]
--ignore-warnings
Suppress warnings about inconsistencies in length between input and parsed strings and missing
characters. These warning messages are often related to non-standard latex or latex constructions
with a syntax unknown to "latexdiff" but the resulting difference argument is often fully functional
anyway, particularly if the non-standard latex only occurs in parts of the text which have not
changed.
--label=label or -Llabel
Sets the labels used to describe the old and new files. The first use of this option sets the label
describing the old file and the second use of the option sets the label for the new file, i.e. set
both labels like this "-L labelold -L labelnew". [Default: use the filename and modification dates
for the label]
--no-label
Suppress inclusion of old and new file names as comment in output file
--visible-label
Include old and new filenames (or labels set with "--label" option) as visible output.
--flatten
Replace "\input" and "\include" commands within body by the content of the files in their argument.
If "\includeonly" is present in the preamble, only those files are expanded into the document.
However, no recursion is done, i.e. "\input" and "\include" commands within included sections are not
expanded. The included files are assumed to
be located in the same directories as the old and new master files, respectively, making it possible
to organise files into old and new directories. --flatten is applied recursively, so inputted files
can contain further "\input" statements. Also handles files included by the import package
("\import" and "\subimport"), and "\subfile" command.
Use of this option might result in prohibitive processing times for larger documents, and the
resulting difference document no longer reflects the structure of the input documents.
--filter-script=filterscript
Run files through this filterscript (full path preferred) before processing. The filterscript must
take STDIN input and output to STDOUT. When coupled with --flatten, each file will be run through
the filter as it is brought in.
--ignore-filter-stderr
When running with --filter-script, STDERR from the script may cause readability issues. Turn this
flag on to ignore STDERR from the filter script.
--help or -h
Show help text
--version
Show version number
Internaloptions
These options are mostly for automated use by latexdiff-vc. They can be used directly, but the API should
be considered less stable than for the other options.
--no-links
Suppress generation of hyperreferences, used for minimal diffs (option --only-changes of latexdiff-
vc)
PredefinedstylesMajortypes
The major type determine the markup of plain text and some selected latex commands outside floats by
defining the markup commands "\DIFadd{...}" and "\DIFdel{...}" .
"UNDERLINE"
Added text is wavy-underlined and blue, discarded text is struck out and red (Requires color
and ulem packages). Overstriking does not work in displayed math equations such that deleted
parts of equation are underlined, not struck out (this is a shortcoming inherent to the ulem
package).
"CTRADITIONAL"
Added text is blue and set in sans-serif, and a red footnote is created for each discarded
piece of text. (Requires color package)
"TRADITIONAL"
Like "CTRADITIONAL" but without the use of color.
"CFONT" Added text is blue and set in sans-serif, and discarded text is red and very small size.
"FONTSTRIKE"
Added tex is set in sans-serif, discarded text small and struck out
"CCHANGEBAR"
Added text is blue, and discarded text is red. Additionally, the changed text is marked with a
bar in the margin (Requires color and changebar packages).
"CFONTCHBAR"
Like "CFONT" but with additional changebars (Requires color and changebar packages).
"CULINECHBAR"
Like "UNDERLINE" but with additional changebars (Requires color, ulem and changebar packages).
"CHANGEBAR"
No mark up of text, but mark margins with changebars (Requires changebar package).
"INVISIBLE"
No visible markup (but generic markup commands will still be inserted.
"BOLD" Added text is set in bold face, discarded is not shown.
"PDFCOMMENT"
The pdfcomment package is used to underline new text, and mark deletions with a PDF comment.
Note that this markup might appear differently or not at all based on the pdf viewer used. The
viewer with best support for pdf markup is probably acroread. This style is only recommended if
the number of differences is small.
Subtypes
The subtype defines the commands that are inserted at the begin and end of added or discarded blocks,
irrespectively of whether these blocks contain text or commands (Defined commands: "\DIFaddbegin,
\DIFaddend, \DIFdelbegin, \DIFdelend")
"SAFE" No additional markup (Recommended choice)
"MARGIN" Mark beginning and end of changed blocks with symbols in the margin nearby (using the standard
"\marginpar" command - note that this sometimes moves somewhat from the intended position.
"COLOR" An alternative way of marking added passages in blue, and deleted ones in red. (It is
recommeneded to use instead the main types to effect colored markup, although in some cases
coloring with dvipscol can be more complete, for example with citation commands).
"DVIPSCOL"
An alternative way of marking added passages in blue, and deleted ones in red. Note that
"DVIPSCOL" only works with the dvips converter, e.g. not pdflatex. (it is recommeneded to use
instead the main types to effect colored markup, although in some cases coloring with dvipscol
can be more complete).
"ZLABEL" can be used to highlight only changed pages, but requires post-processing. It is recommend to
not call this option manually but use "latexdiff-vc" with "--only-changes" option.
Alternatively, use the script given within preamble of diff files made using this style.
"ONLYCHANGEDPAGE"
also highlights changed pages, without the need for post-processing, but might not work
reliably if there is floating material (figures, tables).
"LABEL" is similar to "ZLABEL", but does not need the zref package and works less reliably
(deprecated).
FloatTypes
Some of the markup used in the main text might cause problems when used within floats (e.g. figures or
tables). For this reason alternative versions of all markup commands are used within floats. The float
type defines these alternative commands.
"FLOATSAFE"
Use identical markup for text as in the main body, but set all commands marking the begin and
end of changed blocks to null-commands. You have to choose this float type if your subtype is
"MARGIN" as "\marginpar" does not work properly within floats.
"TRADITIONALSAFE"
Mark additions the same way as in the main text. Deleted environments are marked by angular
brackets \[ and \] and the deleted text is set in scriptscript size. This float type should
always be used with the "TRADITIONAL" and "CTRADITIONAL" markup types as the \footnote command
does not work properly in floating environments.
"IDENTICAL"
Make no difference between the main text and floats.
ConfigurationVariables
"ARRENV" If a match to "ARRENV" is found within an inline math environment within a deleted or added
block, then the inlined math is surrounded by "\mbox{"..."}". This is necessary as underlining
does not work within inlined array environments.
[ Default: "ARRENV"="(?:array|[pbvBV]matrix)"
"COUNTERCMD"
If a command in a deleted block which is also in the textcmd list matches "COUNTERCMD" then an
additional command "\addtocounter{"cntcmd"}{-1}", where cntcmd is the matching command, is
appended in the diff file such that the numbering in the diff file remains synchronized with
the numbering in the new file.
[ Default: "COUNTERCMD"="(?:footnote|part|section|subsection" ...
"|subsubsection|paragraph|subparagraph)" ]
"CUSTOMDIFCMD"
This option is for advanced users and allows definition of special versions of commands, which
do not work as safe commands.
Commands in "CUSTOMDIFCMD" that occur in added or deleted blocks will be given an ADD or DEL
prefix. The prefixed versions of the command must be defined in the preamble, either by
putting them in the preamble of at least the new file, or by creating a custom preamble file
(Option --preamble). For example the command "\blindtext" (from package blindtext) does not
interact well with underlining, so that for the standard markup type, it is not satisfactory to
define it as a safe command. Instead, a customised versions without underlining can be defined
in the preamble:
"\newcommand{\DELblindtext}{{\color{red}\blindtext}}"
"\newcommand{\ADDblindtext}{{\color{blue}\blindtext}}"
and then latexdiff should be invoked with the option "-c CUSTOMDIFCMD=blindtext".
[ Default: none ]
"FLOATENV"
Environments whose name matches the regular expression in "FLOATENV" are considered floats.
Within these environments, the latexdiff markup commands are replaced by their FL variaties.
[ Default: "(?:figure|table|plate)[\w\d*@]*" ]
"ITEMCMD" Commands representing new item line with list environments.
[ Default: \"item" ]
"LISTENV" Environments whose name matches the regular expression in "LISTENV" are list environments.
[ Default: "(?:itemize|enumerate|description)" ]
"MATHENV","MATHREPL"
If both \begin and \end for a math environment (environment name matching "MATHENV" or \[ and
\]) are within the same deleted block, they are replaced by a \begin and \end commands for
"MATHREPL" rather than being commented out.
[ Default: "MATHENV"="(?:displaymath|equation)" , "MATHREPL"="displaymath" ]
"MATHARRENV","MATHARRREPL"
as "MATHENV","MATHREPL" but for equation arrays
[ Default: "MATHARRENV"="eqnarray\*?" , "MATHREPL"="eqnarray" ]
"MINWORDSBLOCK"
Minimum number of tokens required to form an independent block. This value is used in the
algorithm to detect changes of complete blocks by merging identical text parts of less than
"MINWORDSBLOCK" to the preceding added and discarded parts.
[ Default: 3 ]
"PICTUREENV"
Within environments whose name matches the regular expression in "PICTUREENV" all latexdiff
markup is removed (in pathologic cases this might lead to inconsistent markup but this
situation should be rare).
[ Default: "(?:picture|DIFnomarkup)[\w\d*@]*" ]
"SCALEDELGRAPHICS"
If "--graphics-markup=both" is chosen, "SCALEDELGRAPHICS" is the factor, by which deleted
figures will be scaled (i.e. 0.5 implies they are shown at half linear size).
[ Default: 0.5 ]
"VERBATIMENV"
RegEx describing environments like verbatim, whose contents should be taken verbatim. The
content of these environments will not be processed in any way: deleted content is commented
out, new content is not marked up
[ Default: "comment" ]
"VERBATIMLINEENV"
RegEx describing environments like verbatim, whose contents should be taken verbatim. The
content of environments described by VERBATIMLINEENV are compared in line mode, and changes are
marked up using the listings package. The markup style is set based on the chosen mains markup
type (Option -t), or on an analysis of the preamble. Note that "listings.sty" must be
installed. If this file is not found the fallback solution is to treat VERBATIMLINEENV
environments treated exactly the same way as VERBATIMENV environments.
[ Default: "(?:verbatim[*]?|lstlisting" ]
Install Now
PNG Icons
