I use git everyday. You should use git
or some other git-esque system when writing research papers, because it’s a great way to track all of your changes. The
real-world problem is my co-authors don’t use git.
Typically I’ll draft a manuscript, distribute the document (PDF and/or LaTeX) by email, and wait for feedback.
Some will provide changes to the LaTeX, others will annotate the PDF, some will provide itemised text responses, and some will print it,
scribble on it, and hand me a butchered manuscript.
After sending the manuscript around once to everyone, I don’t want them to have to read everything through again: they should just notice the changes. It’s easier, and faster for
everyone. To accomplish this I’ve installed latexdiff. It’s a Perl script that highlights the differences between two TeX files. You can download it here, or just read about it.
Once latexdiff is installed, let’s initiate a git repository and start writing a paper.
When I make major revisions to a paper (e.g., when I send out copies to co-authors), I want to use latexdiff to automatically create a file that highlights the changes from
the previous version. Let’s set up a post-commit hook by putting the following code into a new file in your folder called .git/hooks/post-commit. Make sure this is executable by using chmod +x .git/hooks/post-commit. Now any time we commit to the repository, this script will run.
Okay, now let’s work with an example of a “real” paper. Here’s the LaTeX for a manuscript:
Let’s commit this to the repository, and make a note in the commit message that this is version v0.1 of the paper.
I send this version around to my co-authors Alice and Bob, and wait for their responses. Each time someone responds, I implement their suggestions and commit the changes to the repository.
> You forgot my last name! I think you’re missing a constant from Equation 1. Also, can we use “simply not” instead of “not simply”?
We make the changes, then commit to the repository.
> You should be more explicit in the conclusions. Perhaps mention how Buster should act accordingly? Also, you forgot my last name!
Bob’s suggestions are good, so we implement them. Here’s what the final LaTeX looks like:
Since Bob is the last of our co-authors, once we’ve implemented his changes we can call this v0.2. Notice in this commit message that Revision v0.2 can be anywhere in the commit message, and is not case-sensitive.
Notice the extra message at the start? Our post-commit hook has run and seen that we have more than one revision in our commit history. It’s found the previous version, made a comparison on the two TeX files and compiled it for us!
Take a look:
Now we can send out the revised version (manuscript.pdf), as well as a PDF with the highlighted changes between version 0.1 and version 0.2 (manuscript-revisions-v0.2.pdf). This will happen anytime you commit with something like revision vX in the commit message. Also you can be as pedantic as you want: revision v1, revision v32.4, revision v0.1.3, etc are all acceptable. Easiest way to create automatic PDF diff files, ever!
Here’s what manuscript-revisions-v0.2.pdf looks like:
This makes it infinitely easier for your co-authors to digest what has changed, and will drastically shorten the turnaround between manuscript revisions. If you were wondering, it doesn’t take the fist TeX file it sees; it finds the TeX file that has been edited the most times in the repository, which is probably your manuscript!