LATEXDIFF(1)

📦 version 2026.0, in alpine 3.24

okay so bestie, this is the latexdiff manual page, and it's literally the tool for determining and marking up differences between two latex files. Buckle up, because this one is thorough in the most iconic way 💅.

💖 NAME 💖

latexdiff — determine and markup differences between two latex files ✨

🌸 SYNOPSIS 🌸

latexdiff [ OPTIONS ] old.tex new.tex > diff.tex

🦋 DESCRIPTION 🦋

Briefly, latexdiff is a utility program that helps you manage revisions of latex documents. It compares two valid latex files — here called old.tex and new.tex — finds significant differences between them (i.e., ignoring the number of white spaces and position of line breaks), and adds special commands to highlight the differences. Where visual highlighting is not possible, e.g. for changes in the formatting, the differences are nevertheless marked up in the source. Note that old.tex and new.tex need to be real files (not pipes or similar) as they are opened twice (unless the --encoding option is used).

The program treats the preamble differently from the main document. Differences between the preambles are found using line-based differencing (similarly to the Unix diff command, but ignoring white spaces). A comment, %DIF >, is appended to each added line, i.e. a line present in new.tex but not in old.tex. Discarded lines are deactivated by prepending %DIF <. Changed blocks are preceded by comment lines giving information about line numbers in the original files. Where there are insignificant differences, the resulting file diff.tex will be similar to new.tex. At the end of the preamble, the definitions for latexdiff markup commands are inserted. In differencing the main body of the text, latexdiff attempts to satisfy the following guidelines (in order of priority):

  1. If both old.tex and new.tex are valid LaTeX, then the resulting diff.tex should also be valid LateX. (NB If a few plain TeX commands are used within old.tex or new.tex then diff.tex is not guaranteed to work but usually will).
  2. Significant differences are determined on the level of individual words. All significant differences, including differences between comments should be clearly marked in the resulting source code diff.tex.
  3. If a changed passage contains text or text-producing commands, then running diff.tex through LateX should produce output where added and discarded passages are highlighted.
  4. Where there are insignificant differences, e.g. in the positioning of line breaks, diff.tex should follow the formatting of new.tex.

For differencing, the same algorithm as diff is used but words instead of lines are compared. An attempt is made to recognize blocks which are completely changed such that they can be marked up as a unit. Comments are differenced line by line but the number of spaces within comments is ignored. Commands including all their arguments are generally compared as one unit, i.e., no mark-up is inserted into the arguments of commands. However, for a selected number of commands (for example, \caption and all sectioning commands) the last argument is known to be text. This text is split into words and differenced just as ordinary text (use options to show and change the list of text commands, see below). As the algorithm has no detailed knowledge of LaTeX, it assumes all pairs of curly braces immediately following a command (i.e. a sequence of letters beginning with a backslash) are arguments for that command. As a restriction to condition 1 above it is thus necessary to surround all arguments with curly braces, and to not insert extraneous spaces. For example, write

\section{\textem{This is an emphasized section title}}

and not

\section {\textem{This is an emphasized section title}}

or

\section\textem{This is an emphasized section title}

even though all varieties are the same to LaTeX (but see --allow-spaces option which allows the second variety).

For environments whose content does not conform to standard LaTeX or where graphical markup does not make sense all markup commands can be removed by setting the PICTUREENV configuration variable, set by default to picture and DIFnomarkup environments; see --config option). The latter environment (DIFnomarkup) can be used to protect parts of the latex file where the markup results in illegal markup. You have to surround the offending passage in both the old and new file by \begin{DIFnomarkup} and \end{DIFnomarkup}. You must define the environment in the preambles of both old and new documents. I prefer to define it as a null-environment,

\newenvironment{DIFnomarkup}{}{}

but the choice is yours. Any markup within the environment will be removed, and generally everything within the environment will just be taken from the new file.

It is also possible to difference files which do not have a preamble. In this case, the file is processed in the main document mode, but the definitions of the markup commands are not inserted.

All markup commands inserted by latexdiff begin with \DIF. Added blocks containing words, commands or comments which are in new.tex but not in old.tex are marked by \DIFaddbegin and \DIFaddend. Discarded blocks are marked by \DIFdelbegin and \DIFdelend. Within added blocks all text is highlighted with \DIFadd like this: \DIFadd{Added text block}. Selected safe commands can be contained in these text blocks as well (use options to show and change the list of safe commands, see below). All other commands as well as braces { and } are never put within the scope of \DIFadd. Added comments are marked by prepending %DIF > .

Within deleted blocks text is highlighted with \DIFdel. Deleted comments are marked by prepending %DIF < . Non-safe command and curly braces within deleted blocks are commented out with %DIFDELCMD < .

🎀 OPTIONS 🎀

🧚 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, -t markupstyle — 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
LUAUNDERLINE

Default: UNDERLINE

  • --subtype=markstyle, -s markstyle — 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

⚠️ Heads up: subtype LABEL is deprecated 💀
  • --floattype=markstyle, -f markstyle — 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, -e enc — 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 assumed. Note that ASCII (standard latex) is a subset of utf8.

  • --preamble=file, -p file — 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:
    • 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.

🎀 Configuration 🎀

  • --exclude-safecmd=exclude-file, -A exclude-file, --exclude-safecmd="cmd1,cmd2,..."
  • --replace-safecmd=replace-file
  • --append-safecmd=append-file, -a append-file, --append-safecmd="cmd1,cmd2,..."

Okay so these three besties let you exclude from, replace, or append to the list of regular expressions (RegEx) that match commands which are safe to use inside the scope of a \DIFadd or \DIFdel command 💅. The file has to contain one Perl-RegEx per line (comment lines starting with # or % get ignored, ngl they're just vibes). Heads up: the RegEx needs to match the whole of the token, i.e. /^regex$/ is implied, and 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, -X exclude-file, --exclude-textcmd="cmd1,cmd2,..."
  • --replace-textcmd=replace-file
  • --append-textcmd=append-file, -x append-file, --append-textcmd="cmd1,cmd2,..."

Same energy, but for the list of regular expressions matching commands whose last argument is text 💖. See the entry for --exclude-safecmd directly above for further details (it's literally the same rules, just a different list, iykyk).

  • --replace-context1cmd=replace-file
  • --append-context1cmd=append-file, --append-context1cmd="cmd1,cmd2,..."

Replace or append to the list of regex matching commands whose last argument is text but which need a particular context to work — like, \caption will only work within a figure or table, bestie 🎀. These commands behave like text commands, except when they occur in a deleted section — then they get disabled, but their argument is still shown as deleted text. Iconic behaviour honestly.

  • --replace-context2cmd=replace-file
  • --append-context2cmd=append-file, --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 the --replace-context2cmd option to just select the commands which should be processed and are not used repeatedly in the preamble 😭.

  • --exclude-mboxsafecmd=exclude-file, --exclude-mboxsafecmd="cmd1,cmd2,..."
  • --append-mboxsafecmd=append-file, --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 🦋.

  • --config var1=val1,var2=val2,... or -c var1=val1,..
  • -c configfile

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)
  • MATHENV (RegEx)
  • MATHREPL (String)
  • MAXCHANGESLETTER (Integer)
  • MINWORDSBLOCK (Integer)
  • PICTUREENV (RegEx)
  • SCALEDELGRAPHICS (Float)
  • --add-to-config varenv1=pattern1,varenv2=pattern2,...

For configuration variables that are a regular expression (essentially those ending in ENV, COUNTERCMD and CUSTOMDIFCMD, see list above), this option is an alternative way to modify them 🌸. Instead of setting the complete pattern, with this option it's 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-preamble — Print generated or included preamble commands. 👑
  • --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, the behaviour is different dependent whether old.tex or new.tex files are specified 💀. If they are not specified, then the initial setup is shown. If they are specified, then the full configuration is shown, which includes some additions of internal commands, and modifications based on what packages are present on the system, or are used in the .tex files. Either way, no differencing takes place. Periodt.

✨ Other configuration options ✨

  • --allow-spaces — Allow spaces between bracketed or braced arguments to commands 💖. Note that this option might have undesirable side effects (unrelated scope might get lumped with preceding commands) so it 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 the 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 \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 💀.

  • --no-del — Suppress deleted text from the diff. It is similar in effect to the BOLD style, but the deleted text is not just invisible in the output — it is also not included in the diff text file. This can be more robust than just making it invisible 😭.
  • --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 the \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 (which, honestly, same).
  • --driver=type — Choose driver for the changebar package (only relevant for styles using changebar: CCHANGEBAR CFONTCHBAR CULINECHBAR CHANGEBAR) 🔥. Possible drivers are listed in the 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. So like, don't panic 🫶.
  • --label=label or -L label — 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 the --label option) as visible output ⭐.
  • --flatten — ok so this one goes in and replaces every \input and \include command inside the body with the actual content of the files they point at 💖. If \includeonly is chillin' in the preamble, then only those files get expanded into the document, no cap. Important bit though: no recursion is done — meaning \input and \include commands sitting inside the included sections do not get expanded by this. The included files are assumed to be located in the same directories as the old and new master files respectively, which is what makes it possible to organise files into old and new directories 🗂️. Oh and also, --flatten is applied recursively, so inputted files can contain further \input statements. It also handles files included by the import package (\import and \subimport), plus the \subfile command.
Heads up bestie: using 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 — runs files through this filterscript (full path preferred) before processing. The filterscript must take STDIN input and output to STDOUT. When you couple it with --flatten, each file gets run through the filter as it's brought in 🫶.
  • --ignore-filter-stderr — when running with --filter-script, STDERR from the script may cause readability issues. Flip this flag on to just ignore STDERR from the filter script 🙈.
  • --help or -h — show help text ✨
  • --version — show version number 👑

🛠️ Internal options

These ones are mostly for automated use by latexdiff-vc. You can use them directly, but ngl 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).

🎀 Predefined styles 🎀

💐 Major types

The major type determines 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) 😬.
  • LUAUNDERLINE — added text is underlined and blue, discarded text is struck out and red (Requires lua-ul package + LuaLaTeX) 🦋.
  • 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 (also see --no-del option for another possibility to hide deleted text) 💪.
  • 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) 💀.

🧚 Float Types

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. Simple. Iconic. Periodt 💅.

🔧 Configuration Variables

  • 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" ]

  • MAXCHANGESLETTER — okay so when latexdiff clocks that a single word got swapped out, it tries to be extra and figure out the changes at letter level ✨. But here's the tea: if there are like, a lot of changes, the word was probably just replaced wholesale, and letter-level markup would be straight-up confusing instead of helpful. In that case, latexdiff falls back to showing the replacement at word level. The way it tells the two apart is lowkey simple: it counts the number of distinct additions and deletions (not the number of letters changed, bestie!), and only if they're less than or equal to MAXCHANGESLETTER does the letter-level markup get used. Sensible values are 0, 1, or 2 🎀. 0 disables letter-level markup completely. 1 only allows a single addition or deletion — perfect for a typo correction or changing singular/plural of a verb, but no substitution. 2 allows one substitution (or two additions or deletions) — and this will sometimes result in different words being marked up at letter level, e.g. they-> there will show deleted "y" and added "re", which is often not desirable 🙈.

[ Default: 1 ]

  • MINWORDSBLOCK — the minimum number of tokens required to form an independent block 🧱. This value gets 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 that 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're shown at half linear size) 🦋.

[ Default: 0.5 ]

  • VERBATIMENV — a 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 — a 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 main 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 exactly the same way as VERBATIMENV environments.

[ Default: (?:verbatim[*]?|lstlisting ]

🎀 DIRECTIVES 🎀

Sometimes the output latexdiff produces is just... not it 😭, or some complicated constructions even lead to a difference tex file that leads to an error 💀. It is possible to give latexdiff some hints to control the markup by placing some special comments, termed directives, into the tex file 🫶.

Directives mark blocks by paired BEGIN and END directives. It's important that the directives are written exactly as specified below, i.e., all letters need to be capitalised and there has to be exactly one space between BEGIN/END and the block type. However, after the directive arbitrary comments can be added 👑.

Nesting of blocks or overlapping blocks are not parsed correctly and will cause undefined behaviour ⚠️.

Blocks can be spanning across scope boundaries; they can also be used in the last argument of text commands. If they appear in the arguments of other commands, then latexdiff will assume they were placed before or after the command; it's best to avoid this, though 🙈.

✨ DIFADD block ✨

...
%BEGIN DIFADD
...
%END DIFADD
...

Everything enclosed between the %BEGIN DIFADD and %END DIFADD directives will be treated as atomistic addition to the text 💖. The interior will be marked up as added text following the normal rules for what is marked up. A use case for this directive is when a paragraph has been changed substantially but retains some of the phrasing of the original paragraph. As latexdiff prefers to find a minimal difference between two files, such a configuration will usually lead to a fragmented markup, with several added and deleted sentences or parts of sentences and a few remaining phrases marked as unchanged 😵‍💫. With the use of this directive it's possible to mark the whole modified segment as new, which will then be marked-up en bloc as new, and the old part as one block of deleted material — which is usually clearer than the fragmented default markup 🔥. DIFADD block directives must be placed into the body of the new file. Those directives are ignored in the preamble or in the old file.

💜 DIFDEL block 💜

...
%BEGIN DIFDEL
...
%END DIFDEL
...

Everything enclosed between the %BEGIN DIFDEL and %END DIFDEL directives will be treated as atomistic deleted text 🌈. The interior will be marked up as deleted text following the normal rules for what is marked up. DIFDEL block directives must be placed into the body of the old file. Those directives are ignored in the preamble or in the new file. The use case is similar to that of the DIFADD blocks, but the hint is placed in the old file 🎀. In most cases, it is sufficient to either hint in the old file with a DIFDEL block or in the new file with a DIFADD block and latexdiff will take care of the rest ✨.

🦋 DIFNOMARKUP block 🦋

...
%BEGIN DIFNOMARKUP
...
%END DIFNOMARKUP
...

The text between the markers will be included in the diff algorithm but no actual markup will be made in this part of the text. It will show the new text only and suppress the old text 🙈. If the text immediately above the DIFNOMARKUP block has been added, a \DIFaddend will be placed directly above the %BEGIN DIFNOMARKUP line and any open \DIFadd command terminated — equivalently for deleted blocks and for text added or deleted immediately after the %BEGIN DIFNOMARKUP 🫶.

The main purpose of this command is to salvage the situation if latexdiff has produced invalid or visually unacceptable output — markup in the offending passage can be suppressed by surrounding it with DIFNOMARKUP directives and rerunning latexdiff, thus enabling markup of the rest of the document (but please continue to report such failures of latexdiff as described below, so that latexdiff can be improved 💖). This pair of directives must be placed in the new file and will be ignored in the old file (or the preambles of either file) ⭐.

💬 COMMON PROBLEMS AND FAQ 💬

Bestie, this is the part where we get real about the stuff that will absolutely make you go "wait, why is it doing THAT 😭". Every single one of these is a known thing, you're not broken, and there are fixes. Let's go 🫶

Changed citations result in overfull boxes — okay so here's the tea 🍵: there's an incompatibility between the ulem package, which latexdiff uses for underlining and striking out in the UNDERLINE style (aka the default style), and the way citations are generated. To be able to mark up citations properly, they get enclosed with an \mbox command. And because mboxes can't be broken across lines, this procedure frequently results in overfull boxes, possibly obscuring the content as it extends beyond the right margin 😬. Same thing happens for some other packages too (e.g., siunitx). If this is a problem, you've got several possibilities:

  1. Use CFONT type markup (option -t CFONT): if this markup is chosen, then changed citations are no longer marked up with the wavy line (additions) or struck out (deletions), but are still highlighted in the appropriate color, and deleted text is shown with a different font. Other styles not using the ulem package will also work 💅
  2. Choose option --disable-citation-markup which turns off the marking up of citations: deleted citations are no longer shown, and added citations are shown without markup. (This was the default behaviour of latexdiff at versions 0.6 and older, fyi.) For custom packages you can define the commands which need to be protected by \mbox with --append-mboxsafecmd and --excludemboxsafecmd options (submit your lists of command as feature request at github page to set the default behaviour of future versions, see section 6 🫶)
  3. If you are using luatex >= 1.12.0 you can use option LUAUNDERLINE that uses lua-ul instead of ulem for underlining, which does not have this problem (experimental feature ✨)

Changes in complicated mathematical equations result in latex processing errors. — try option --math-markup=whole. If even that fails, you can turn off mark up for equations with --math-markup=off. Crisis averted 😌

Deleted parts in equations are not struck out but underlined. — this is a limitation of the ulem package that implements the strike-out, ngl. If you use the amsmath package, then the strike-out command is redefined in such a way that deleted passages are wrapped with \text command; adding \usepackage{amsmath} to your preamble will trigger this behaviour 👑. (If amsmath is not included directly, but imported by another package, latexdiff will not be able to detect its availability; in this case you can give latexdiff a hint with option --packages=amsmath.)

How can I just show the pages where changes had been made? — use options --s ZLABEL (some postprocessing required) or -s ONLYCHANGEDPAGE. And latexdiff-vc --ps|--pdf with --only-changes option takes care of the post-processing for you (requires zref package to be installed) 🎀

The character encoding breaks when running latexdiff from powershell. — this problem is not limited to latexdiff and has to do with the default settings of powershell in Windows 🙈. It is recommended to use cmd instead.

💀 KNOWN BUGS 💀

Option --allow-spaces is not implemented entirely consistently. It breaks the rules that number and type of white space does not matter, as different numbers of inter-argument spaces are treated as significant. Yeah, I know. It's giving "we know, it's on the list" 😅

Please submit bug reports using the issue tracker of the github repository page https://github.com/ftilmann/latexdiff.git, or send them to tilmann -- AT -- gfz-potsdam.de. Include the version number of latexdiff (from comments at the top of the source or use --version). If you come across latex files that are error-free and conform to the specifications set out above, and whose differencing still does not result in error-free latex, please send me those files, ideally edited to only contain the offending passage as long as that still reproduces the problem. If your file relies on non-standard class files, you must include those. I will not look at examples where I have trouble to latex the original files. Fair enough fr fr 🫡

👀 SEE ALSO 👀

latexrevise, latexdiff-vc

🌍 PORTABILITY 🌍

latexdiff does not make use of external commands and thus should run on any platform supporting Perl 5.6 or higher ✨. If files with encodings other than ASCII or UTF-8 are processed, Perl 5.8 or higher is required.

The standard version of latexdiff requires installation of the Perl package Algorithm::Diff (available from www.cpan.org - http://search.cpan.org/~nedkonz/Algorithm-Diff-1.15) but a stand-alone version, latexdiff-so, which has this package inlined, is available, too 🎀. latexdiff-fast requires the diff command to be present.

👑 AUTHOR 👑

Version 1.4.0 Copyright (C) 2004-2024 Frederik Tilmann

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License Version 3

Contributors of fixes and additions: V. Kuhlmann, J. Paisley, N. Becker, T. Doerges, K. Huebner, T. Connors, Sebastian Gouezel and many others. Thanks to the many people who sent in bug reports, feature suggestions, and other feedback 💖

And that's a wrap on the whole page, bestie!! 🦋 This one shipped from perl v5.38.2, dated 2025-12-30, and it's the LATEXDIFF(1) man page. Now go diff some latex and slay ✨💅

📦 where this page comes from