Introduction

To collaboratively and concurrently work on a project like a research paper, it has proven extremely to utilize services of a distributed version control system. Basically, this provides the following features:

• Commits are transactions based and not file based as in other version control systems like the deprecated CVS and SVN.
• Very powerful diff and merge algorithms that allow multiple authors to work on the same file at the same time (at least in different places of it).
• Distributed repositories: Every author has their own local copy of the entire repository (meaning everything relevant for the paper in question), including a history of all past changes (which can be inspected at the authors leisure).

By the way, repository can be read synonymously with manuscript or project in this little tutorial.

The initial work flow is the following:

1. Obtain a local copy of the repository from this server.
2. Edit the paper and add more files as you please.
3. Commit your changes locally, pull in changes by others from the server, let git merge all the different change sets.
4. Push your local changes ("commits") to the server.

Any subsequent work flow then only consists of the later steps, i.e.,

1. pull in changes by others from the server;
2. edit the paper and add more files as you please;
3. commit your changes locally, pull in changes by others from the server, let git merge all the different change sets;
4. push your local changes ("commits") to the server.

Does that sound too complicated? I hope not.

Installation and basic setup

In order to get started, you need to install git on your machine. You can download the most recent version from git-scm.com. Git runs on essentially all operating systems. For UNIX based systems you might as well use your favorite package manager to install git (apt-get install git or fink install git or port install git etc.).

Once git is installed, open a command line window and enter some basic configuration:

$ git config --global user.name "Bjoern Rueffer"
$ git config --global user.email "my@email.address"

This step is to ensure that later one can distinguish who made which change to a repository.

Now you need to have an SSH key pair. The pair consists of a private and a public key and this is needed so that in the sequel you will never have to type in any passwords. If you already have one (see if you have the two files mentioned below), please just send me you public key file and you are done. If you don't have a key pair yet, you need to create one.

If you are working on a UNIX machine (or Mac for that matter) you will most likely have OpenSSH installed on your system. If you are using Windows, you need to install a SSH client from here, if you don't already have one. Now assuming that you have SSH on your system, go to the command line window and type

$ ssh-keygen

You may hit enter at all the questions you be asked here. Important is to note down the location of the key files that are being generated. Usually, that looks like

Your identification has been saved in /home/username/.ssh/id_rsa.
Your public key has been saved in /home/username/.ssh/id_rsa.pub.

The second line contains the file name of your public key. You need to send me that file via email. (If you are concerned about his, you might want to read about public key authentication in your favorite textbook on cryptography or on Wikipedia.)

And this is it. The next step is to get a local copy of the repository you are planning to work with.

In fact, you can have different SSH keys for different machines that you are using, say your laptop computer and your desktop machine. In that case you can send me a key for each machine.

Addendum: Actually, pure HTTPS access using a password is possible, too. That way you don't have to generate a key pair or use SSH at all, but you will have to enter your password quite frequently. Just ask me about it if you are interested. [19.06.2011]

Cloning: Getting a local copy of a repository for the first time

You only perform this step once at the very beginning to obtain your initial copy of a repository. In order for this step to work, you will need to have completed the installation procedure above.

Cloning is simple. Just decide where you want your working copy to reside on your local hard drive and change into that directory on the command line. Then type

$ git clone git@repo.rueffer.info:<name-of-the-repository>

which will create a directory <name-of-the-repository> and populate it with the current state of the repository, that is, all files that it currently comprises at their latest version.

Now can go ahead and edit and compile the paper.

Committing: Taking snapshots of local changes

This is a step that you might want to perform frequently. Whenever you made a significant or even not very significant change, that might be somehow not related from other changes you are planning to make, you should take a snapshot of the current state of the project. This is essentially what a commit does. Commits can be reverted, and they can also be applied in a different order than the one they have been created in. One can even revert individual commits from the history.

So for example, assuming you wrote a fantastic introduction to your paper, then changed some other parts of the paper, then modified the introduction, and again changed other parts of the paper, and finally you decide you want to revert the introduction to its initial fantastic state, but keep the rest of the paper as it is. Well, frequently making commits is a way that lets you do this.

And here is how. Again we are working from the command line, and assume that we are somewhere in the working directory of the repository.

(edit existing files, create new files)
$ git add <new files>
$ git commit -am "In this commit I rewrote the introduction to reflect suggestions from A.U.Thor"

What you see here is this: First you have edited the manuscript and potentially contributed a new figure in a separate file. Git does not yet know about this file, so we have to add it to the repository. That is what the second line does.

Then we do the actual commit. Note that it is always a good idea to provide a brief log message describing what this commit has changed. This can help later to locate this particular modification in case you want to revert it. It also allows your collaborators to get an idea, what part of the paper you have been working on or what exactly you might have changed in the middle of a long and complicated proof.

To make your local commits visible to your collaborators, you need to push them to the server.

Pulling new versions from the server

To bring your local repository copy to the latest state, you can issue the following command:

$ git pull origin master

This tells git to pull into your local repository all the changes made on the remote side (from your peers by pushing their changes to the server, see the next section about pushing).

One important note: Pulling can fail (but that is rare), when for example two people have edited the same paragraph and git cannot decide how to merge the two change sets on its own. In this case markers will be added to the file(s) in questions. They look like <<<<< or >>>>> and you can search for them, edit the point in the file and remove the markers and then do a

$ git commit -am "I have merged conflicting change sets in file xyz."

After such a merge you should push this merge to the server, as detailed next.

Pushing local changes to the server to make them visible to others

The last piece of useful information about collaboratively working on a paper with git is how you let your peers know about you modifications. Once you have locally committed all your changes, you need to transfer them to the server. This is called pushing and done via

$ git push origin master  

And this is essentially all there is to know to get you started. If you have questions, feel free to email me, or we can walk through the relevant steps together on Skype.

Conclusions

Git is a very powerful tool. If you have used CVS or SVN before then working with git should not be too much trouble. The only real difference is that whereas in CVS and SVN you would just perform a

$ cvs commit -m "My log message."

or

$ svn commit -m "My log message."

to publish your local changes to your colleagues, now you have to issue two commands

$ git commit -am "My log message."
$ git push origin master

And this little extra typing is compensated by the speed of the git operations, the benefit of your own local and independent copy of the repository, as well as a rich set of features offered by git which you can read more about in the official and contributed git documentation.

How to change your password for HTTPS access

In the event of a forgotten password, or when I never gave you a password but you do have SSH access, or just because you don't like the password that I have assigned to you, you may define a new password for your account. Just issue a

$ ssh git@repo.rueffer.info htpasswd    

at the command line, and type in your new password when the new password prompt appears.

Reduced typing for git pull/push

When you pull/push from/to a git repository, regardless of it being hosted here or elsewhere, git may complain if you just say

$ git pull  

or

$ git push

and ask you to specify a branch (for the default remote, which is called origin. You can once and for all set this default branch to master as follows:

$ git config --global branch.master.remote origin
$ git config --global branch.master.merge refs/heads/master  

Troubleshooting

Testing that your SSH key is working properly

Once you have sent me your SSH key, and before you actually clone a repository, you can verify that git, ssh, and this server work together as anticipated. When you do a

$ ssh git@repo.rueffer.info

at the command line, you should see some ssh related status messages, potentially get asked whether you want to permanently add the host key of this server to your key ring of known hosts (yes), and then the server software should greet you with something along the lines

hello your_username, the gitolite version here is x.yz (Debian)
the gitolite config gives you the following access:  
     R   W      ResearchProjects/XYZ
    @R_ @W_     test-repository
Connection to repo.rueffer.info closed.

If you see that, then you have configured your ssh installation correctly.