Posts Tagged ‘subfile’

git-latexdiff errors? Workaround: using latexdiff manually allows fixing broken things

December 4, 2017 Leave a comment

In a previous post we have highlighted git-latexdiff, which visually highlights the changes between two versions of the same latex file managed with git – without you being required to checkout any versions of that file yourself. In certain cases git-latexdiff might terminate with errors instead of producing a visual diff file. For example, it might struggle with broken latex code, broken figures, certain usage of subfiles, etc. In such cases, it might help to manually do what git-latexdiff would do fully automatically for you. Here’s a simple step-by-step explanation of how you could achieve visual highlighting even with broken Latex files:

  • Have the repository R2 available, which contains the file F in the newer version you want compared. Copy the repository R2 to a different folder R1 (you could do this on other ways too, but with copying you can hardly mess things up). In the copied folder checkout the version of the repository which contains F in the older version you want compared. Therefore, R2 contains F in the new version and R1 contains F in the old version now.
  • You can now fix both versions of F  should they contain broken latex code. F essentially needs to compile in both R2 and R1.
  • If you run into troubles with figures (also in subsequent steps) it might be helpfull to add the “draft” parameter to the documentclass. This can be done in both F files or in the diff.tex generated later. It disables figures in the documents, which causes less problems later in case figures are part of what prevents latexdiff, pdflatex, or one of the other tex tools from doing their jobs. This might also the case if figures have both been added and removed, or if figure paths have changed between those versions.

After those preparations, in your terminal run the following command from somewhere outside both repositories:

latexdiff --append-safecmd=subfile R1/path/to/F R2/path/to/F --flatten > diff.tex

The option


makes the subfile command safe to use within the scope of the “\DIFadd” or “\DIFdel” commands, which latexdiff uses to mark differences between versions. The option


replaces “\input” and “\include” commands within body by the content of the files in their argument. This makes all content of the document appear in your highlighted diff in the end. If the latexdiff-command succesfully generated a diff.tex file, copy this file into R2 or R1, right next to where F is located. You should now be able to compile and show the pdf file:

pdflatex diff.tex && biber diff && pdflatex diff.tex && evince diff.pdf

Fixing even more problems

In case you run into errors during compilation using the method above you might be able to manipulate the diff.tex file. If this does not help and if you are just interested in differences in the plain text there is an even stronger workaround you can try: you can copy the important parts of the content of your main .tex files in both R1 and R2 into newly created – and therefore clean – dummy.tex files. The important part of the text will usually be textual paragraphs, and more importantly for big documents, includes of subfiles. The dummy.tex files need to be of the same document class (e.g. a book class document will need a clean book again to work).  Remember to do this in an identical way in both R1 and R2. Afterwards you can compare the dummy.tex files using latexdiff (instead of the original main files). Doing so can circumvent many different types of problems that might be introduced due to code in custom Latex .cls or .sty files that is either unsupported by latexdiff and/or is broken in some way.