Distributed version control software (git, mercurial, …) provides a safe and convenient means for people to collaborate on projects, including the writing of academic papers using latex. Although there are various ways of setting up an online repository, perhaps the fastest way to start is by using Drop Box or Google Drive (or equivalent) to share a repository for a specific project.
Warning: If two people ‘push’ to the repository at the same time then corruption may occur. Therefore, pushes should be infrequent and/or coordinated via email. (Although ending up in this situation is best avoided, it is possible to recover by recreating the shared repository from the local repositories.)
Note: A long hypen (—) actually means two hyphens next to each other, which is the standard way of specifying ‘long options’ on the command line.
The following instructions are valid for linux or Mac, using a recent version of git (tested with git version 18.104.22.168).
Installing and Configuring Git
Installing git is straightforward; just go to the download page. To configure git, at a minimum, run:
git config —global user.name “Jonathan Manton”
git config —global user.email “email@example.com”
If you want to learn more about git, view the free online book.
To change the default ‘merge’ program to vimdiff, run:
git config —global merge.tool vimdiff
To automatically ignore certain files globally, create the file (any filename will do) ~/.gitignore_global and place in it something like:
git config —global core.excludesfile ~/.gitignore_global
Note that it is “excludesfile” and not “excludefiles”! You will not receive an error if you type the wrong name because all git config –global does is insert entries into the file ~/.gitconfig (this file can be edited by hand if you prefer).
Creating the Shared Repository
(Only the person creating the shared repository need read this section.) Create a new directory in Drop Box or Google Drive, and change directory into it:
Initialise the git repository:
git init —bare
Move to where you would like to have your local copy of the paper (not on Dropbox!) then clone the repository and change directory into it:
git clone ~/Dropbox/NewPaper.git
Do not worry about the warning that we have cloned an empty repository. We are about to populate it before sharing with our collaborators.
Create a .gitignore file with the following contents:
Create skeleton files for the project (e.g. a tex file and a bib file). Run pdflatex and check everything works. Then:
[check that the files produced by pdflatex are ignored (modify .gitignore if this is not the case) and the files that you want are showing up as Untracked files.]
Add the files to git then commit:
git add .
[An editor will open up; type in a message describing this commit, e.g. “Skeleton files”.]
Finally, these changes need to be ‘pushed’ to the shared repository:
git push origin master
The directory NewPaper.git on Drop Box or Google Drive should now be shared with your collaborators so that it shows up on their computers.
Creating a Local Repository
Each person will work in their own local repository. The workflow is described in the next section. This section states how to create a local repository. (The person who created the shared repository, as described in the previous section, already has a local repository, namely ~/Desktop/NewPaper, and can skip this section.)
git clone ~/Dropbox/NewPaper.git
The following is the same for both the person who created the repository as above, and for the other collaborators who have shared access to the Drop Box / Google Drive folder containing the repository.
Henceforth, it is assumed there is a directory called ~/Desktop/NewPaper that contains the local git repository. (Because this local repository was created using ‘git clone’, it knows the location of the shared repository.)
The basic philosophy is that the shared repository ~/Dropbox/NewPaper.git should always contain a version that compiles correctly. Therefore, each collaborator should work in their own local repository, and only ‘push’ changes to the shared ~/Dropbox/NewPaper repository that are ready for sharing. (This is known as the “centralised workflow”. Alternative workflows may be preferable in more complex situations.) Furthermore, since two people pushing at the same time can corrupt the shared repository (a consequence of using Drop Box instead of a proper git repository), pushes should be infrequent and/or coordinated by email.
First check everything is ok:
If you haven’t touched the repository for a while (and you have not made any modifications since the last commit), it is always a good idea to get the latest changes from the shared repository:
Then you can start editing files freely, and running pdflatex to compile. It is a good idea to frequently commit, to allow you to go back to an earlier version should something go wrong. Committing does not affect the shared repository.
git commit -a
[In the text editor which will open up, enter a description of the changes you made.]
If you have created a new file (e.g. my_figure.pdf that will be included in the latex document) that you wish to add to the repository, then just prior to committing (e.g. after you have included the figure in the latex file and ran pdflatex to check it all works), type:
git add my_figure.pdf
git commit -a
The interesting bit comes when you go to push your version to the shared repository. You can try:
If you are lucky, it will work. Otherwise, someone pushed before you, and there are effectively two branches (versions) that must be merged. Provided you have been working on a different part of the latex file from your collaborators, the changes can be merged automatically. Try:
Note that here, we are basically using ‘git pull’ as a shortcut for ‘git fetch’ followed by ‘git merge’. If it worked, we are done, otherwise there are two options. Either edit the files that have conflicts (the output of ‘git pull’ will state which files they are) and fix them manually, or run ‘git mergetool’. At this point, it is best to consult the documentation on basic merge conflicts.
In essense then, the workflow is cyclic: ‘git pull’ followed by the editing of files and one or more ‘git commit -a’, then finally ‘git push’ (followed by ‘git pull’ and ‘git push’ again if a merge was required). At any point, ‘git status’ and ‘git log’ can be run.