Collaboration

Last week, I had to edit a manuscript of a fellow senior scientist. The file he gave me was named (I'm not joking) “manuscript.tex”. Since I usually work on many manuscripts in parallel, I gave it a unique name, edited it, and returned it as “xy_abc13_1.tex” using my usual naming convention with xy being the author's name and abc the journal's.

After other authors had their say, a second round was started and the revised manuscript came back to me with the name “manuscript.tex”. I discovered that several of my changes had been overwritten by later changes or were reverted to the original. When I confronted the author with this irritating fact, he told me that he cannot be held responsible because it's obviously way too complicated to keep track of the changes by renaming the file.

I don't share this point of view, but it's true that there are simpler ways to keep track of changes than to manually rename files, namely, version control systems.

In the following, I show you how to profitably use the version control systems mercurial or, alternatively, git when preparing a manuscript or thesis, and how to combine this version control with latexdiff, an indispensable tool for visualizing the changes made from one revision to the other. Using version control and latexdiff in conjunction is dead simple and has many benefits.

After installing mercurial (or git), we first need a minimum configuration in form of an .hgrc or .gitconfig file containing the name and e-mail address of the local user.

mercurial (.hgrc):

[ui]
username = John Doe <[john.doe@doe.de](mailto:john.doe@doe.de "john.doe@doe.de")>

git (.gitconfig):

[user]
name = John Doe
email = [john.doe@doe.de](mailto:john.doe@doe.de "john.doe@doe.de")

We can now initiate our first project:

mkdir project
cd project
cp example.tex project/
hg init
hg add example.tex
hg commit -m "Original version."

The syntax of git is precisely the same.

Now let's edit our manuscript "example.tex", save the changes (under the same name!), and commit the first revision:

hg commit -m "First revision."

hg log should show you the existence of two revisions: 0 and 1. Git has a more complicated numbering scheme as you will discover when issuing git log.

You're now using a VCS! Now, that wasn't that difficult, was it?

Let's add two more commands to our repertoire. Suppose you edit the file, but you are unhappy with the changes and actually would like to start afresh. A simple hg revert -r 1 brings you back to the state of revision 1. And if you have already committed the changes? In this case, hg update -r 1 defines revision 1 to be new head from which further development will occur.

All right, we can track changes, but how can we visualize them? With LaTeXdiff, of course:

There are several ways to use Latexdiff in conjunction with a VCS.

For example, Latexdiff itself supports git. latexdiff-vc -r f76228 example.tex generates a tex file marking all changes between the current revision and revision f76228. You have to compile this file yourself to obtain a pdf you can view and print. See update at the end of this post.

Mercurial supports external diff programs, and this fragment in your .hgrc allows you to use latexdiff within hg. hg latexdiff -r 0 example.tex > diff.tex creates the tex file containing all differences as above. Once again, you have to compile this file yourself to obtain a pdf you can view and print.

Far more convenient are scripts which automate this procedure. Pål Ellingsen and Paul Hiemstra wrote python scripts supporting mercurial (and additionally git in the case of Paul's script) which automatically generate the pdf containing all changes, including the additional runs necessary for bibtex, and even supporting multi-file documents such as used for writing theses and books. Create and view the diff by

diffLatex.py -r 0 example.tex

or

scm-latexdiff 0:example.tex.

Paul's script also allows us to view the differences between arbitrary revisions: scm-latexdiff 0:example.tex 1:example.tex.

I still give files meaningful names, such as “ob_prb13_1.tex” for my first Physical Review B in 2013. But I will never again worry about file version numbers. What's more, the above scheme is convenient, foolproof (let's see) and entirely transparent. I plan use it for all of my projects in 2013 and the years to come. If only I could convince people to do the same ...

Update 29.07.22:

Recent versions of latexdiff also support explicitely selecting the version control system and compiling the diff file, generating, for example, pdf output:

    latexdiff-vc --hg --pdf -r 0 example.tex

See man latexdiff-vc for further options.