git - Fast Version Control System
Git is a version control system, which was originally written by Linus Torvalds in order to host the Linux kernel. Accordingly, git has been designed to handle very large projects with speed and efficiency. Meanwhile, git is also used by other large projects like Gnome, KDE, Qt, Android, PostgreSQL, and X.org. Of course, git is just as well suited for small personal repositories.
Git falls in the category of distributed source code management tools, similar to e.g. Mercurial or Darcs. Every git working directory is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Still, git stays very space efficient. Furthermore, git is extremely fast, powerful and easy to use.
Git is an open source project covered by the GNU General Public License v2, and is currently maintained by Junio C. Hamano.
Before you can use git on SuperMUC or the Linux Cluster, you have to load the corresponding environment module:
module load git
After that, you can invoke git commands via
git <command> […]
Installing git from source is so simple that the author of this article never checked for the availability of binary packages - until he was to write these lines.
You can obtain binary packages for all major operating systems (Linux, Mac OS, Windows) as well as the source code from git's homepage.
The following should be a reasonable starting point for your personal git configuration. In order that it applies to all your git repositories, you should put these lines into the file $HOME/.gitconfig on all hosts where you are using git:
[user] name = Reiner Zufall email = Reiner.Zufall@dubious.domain.org [color] branch = true diff = true status = true [merge] conflictstyle = diff3
Your name and email address are recorded in any newly created commit. Thus, they should not be that arbitrary and dubious. Apart from setting your name and email address, these lines enable color in the output of certain git commands and specify the style in which conflicted hunks are written out to working tree files upon merge.
It is possible to enable bash's command line completion for git. In order to do so, you can unzip this file, save it in your home directory in $HOME/.bash_git_completions.sh and add the following lines to your $HOME/.bashrc:
if [ -f ~/.bash_git_completions.sh ]; then . ~/.bash_git_completions.sh fi
This will provide support for completing git commands and their subcommands, certain tree and file paths, local and remote branches, as well as local and remote tag names.
Apart from that, your shell prompt may display the currently checked out branch, as soon as you change to a directory the content of which is under git version control. You can enable this very nice feature by unzipping this file, saving it in your home directory in $HOME/.bash_git_prompt.sh and adding the following lines to your $HOME/.bashrc:
if [ -f ~/.bash_git_prompt.sh ]; then . ~/.bash_git_prompt.sh PS1='\u@\h:\w$(__git_ps1 " (%s)")> ' fi
Again, you should do this on all machines, where you are using git. The above files were written by Shawn O. Pearce. After downloading and unpacking the latest source tar ball from git's home page you can also find them (or rather a more recent version) in the directory contrib/completion/.
Cloning Repositories / Pulling Changes to SuperMUC
This section is of concern only to SuperMUC users!
SuperMUC is protected by a very restrictive firewall. As a consequence, users are only permitted to log into SuperMUC using ssh or Grid Middleware from distinguished hosts, which have to be specified in the project application. Additionally, once you are logged into SuperMUC, you are barred from directly reaching any other machine. Unfortunately, this prevents you from cloning or pulling code from external (with respect to SuperMUC) repositories to SuperMUC in a straightforward way.
An example for this is provided by git itself. The straightforward command to obtain git's source code via git itself reads
git clone git://github.com/git/git
On SuperMUC, however, this command will fail because the firewall mentioned above denies access to the external server. Here are two workarounds:
Using ssh port forwarding
In case the straightforward commands fail, first of all you should attempt to use an ssh tunnel. The following example shows how you would translate the above line to ssh port forwarding:
Log into SuperMUC with
ssh -R 12345:github.com:9418 <Your Login>@<SuperMUC Login Node>
This creates an ssh tunnel from the given SuperMUC login node (with TCP source port 12345) to github.com (with TCP destination port 9418). While the first port can be chosen almost arbitrarily, the second port is fixed by the repository server. For example 9418 is the port on which the git-daemon is listening and which is used for the git protocol.
Now, you can clone the repository with
git clone git://localhost:12345/git/git
Please take care that you use a tunnel entrance port that is not already used by another user. So, instead of 12345 you should choose an arbitrary number between 10000 and 65535.
Note, that you cannot use the HTTPS protocol via SSH port forwarding, because the hostnames enlisted in the SSL cerificate do not include localhost.
Using sshfs on your local machine
If for some reason port forwarding does not work, you have the possibility to use sshfs. sshfs allows you to access files on a remote machine through a local directory just as if the files were found on your local machine.
You have to make sure that you are using at least git version 126.96.36.199 on your local machine, or any later release.
sshfs -o workaround=rename <Your Login>@<SuperMUC Login Node>: <Mount Point>
to mount your home directory on SuperMUC to some mount point on your local machine. Note the workaround option, it is essential!
On your local machine you can then execute the commands
cd <Mount Point>/Some/Directory
git clone git://github.com/git/git
Of course, in this way you can also pull or fetch changes from the repository on your local machine.
Pushing Changes from SuperMUC
Please note that pushing changes from SuperMUC to an external repository server has to be supported by the protocol and the server. A protocol which supports pushing is SSH. However, the git protocol does not support pushing and HTTPS does not work via SSH port forwarding. On the other hand, in case you cloned the repository from a public server like github, you probably do not have access via SSH.
In order to push changes from SuperMUC to an external upstream repository, you may utilize git's distributed approach. Just clone (and subsequently pull) your repository from SuperMUC to your laptop or office PC and push your changes from there to the upstream repository. Then you need neither SSH port forwarding nor SSHFS.
git's home page offers plenty of useful links to documentation. Some of these links are given explicitely in the following.
The reference manual offers the official and comprehensive man pages. Thus, we abstained from installing the man pages on our machines.
Newbies can find a nice elementary introduction in the git tutorial. In particular, you learn how to start your git configuration and how you initialize your first git repository. Very easy!
Next, Everyday Git tells you, how you can use git properly in various specific situations, e.g. when you are a standalone developer or when participating in a project together with a couple of other developers.
Subversion users might want to read the SVN Crash Course.