Git

This page should give you an idea about our git repositories and how to use them.

Introduction

Before you start

It's recommended you familiarize yourself with the nomenclature of git and it's basic concepts. The following collection of links provides the necessary entry points:

• RailsConf 2008 Git Tech Talk (Audio/Slides)
• Pro Git (online book, also available in print)
• Git Internals (great e-book for only 9$)
• Git Community Book (free alternative to "Git Internals")
• The Git Parable

Software:

• Linux: comes with your distribution
• Windows: Git, Explorer Integration
• Mac OS X: Git for OS X, alternatively you may install git via Fink or MacPorts

Basic operations

Check out an existing repository

If you want to download a source tree from an existing remote repository and do not intend to upload your changes, you might just clone it like this:

git clone git://server/path/repo.git

Git will then create a subdirectory with the name of the repository (in this case: repo), download the complete repository and checkout the master branch to create your local working tree. If you want to override the default behavior and create a different folder you can simply append its name to the command line used above (just use . for the local directory).

Set up your own repositories

The following example covers the setup of a personal working copy of LAL (LSC Algorithm Library). You can add more projects/repositories as you start working on them. Note: it's recommended you always use a dedicated repository for every single project.

Personal local respository (your actual working tree)

1. Find a suitable place to store the project's source tree (e.g. ~/development)
2. Create a directory to hold the source tree:

   mkdir lal

3. Change to the new directory:

   cd lal

4. Create an empty repository:

   git init

5. Add references to remote repositories (and set "origin" as default)
   • e.g. your personal server-based repository (see next section). This repository will be labeled ''origin'':

     git remote add origin git@git.aei.uni-hannover.de:public/[user]/lal.git
     git config branch.master.remote origin
     git config branch.master.merge refs/heads/master

   • e.g. any tracking repository. This repository will be labeled ''tracking'':

     git remote add tracking git://ligo-vcs.phys.uwm.edu/lal.git

Getting started (required only once!)

1. To get started, fetch an initial version of the desired (here: ''tracking'') remote source tree:

   git fetch tracking

2. Check out your working copy (branch: ''master'') based on the fetched source tree:

   git checkout -b master tracking/origin

3. Copy (push) the initial local working tree (branch: ''master'') to your still empty personal server-based repository (default repo: ''origin'', default branch: ''master''):
   

   git push --all

Daily work

• Update your working with the latest changes in the LAL tracking repository:

  git pull tracking master

• Edit, commit and publish your local changes (see section Commit and publish your changes)

Personal server-based repository (for backup purposes and public access)

These repositories are created and maintained by Carsten Aulbert, Henning Fehrmann and Oliver Bock. Please let us know when you need a new server-based repository!

If you haven't yet done please send us your ssh public-key you want to use to access your repository. To create a new key on Linux just execute the following command:

ssh-keygen -t rsa -b 4096 -C "git@AEI-Hannover" -f ~/.ssh/id_rsa_git@aei-hannover

When you're asked to enter a passphrase you can decide if you want to have one (just press ENTER to skip it). Using no passphrase is less secure (if someone gets hold of your private key) but makes life easier during daily use (you don't have to enter it over and over again). There are ways to use passphrases and enter it just once, but that's ouf the scope of this topic.

You will now find two new files in ~/.ssh/:

• id_rsa_git@aei-hannover (your private key, never send this file to anyone!)
• id_rsa_git@aei-hannover.pub (your public key, we need a copy of this file)

It's recommended that you create a dedicated ssh-alias for our git repository server. You can do so by adding the following to your ~/.ssh/config file (create it if necessary):

host gitaei
	Hostname git.aei.uni-hannover.de
	Port 22
	ForwardAgent no
	ForwardX11 no
	IdentityFile ~/.ssh/id_rsa_git@aei-hannover
	User git

When you use this alias all clone URLs of repositories hosted at AEI Hannover will be simplified like this (taken from the example below):

• Before: git@git.aei.uni-hannover.de:public/[user]/lal.git
• After: gitaei:public/[user]/lal.git

Finally, in order to create a new repository for you please let us know:

• The name (will be part of the clone URL)
• The short description
• Shall it be published via gitweb?
• Shall visitors be able to clone it (read-only)?
• Shall it be personal or shared with others?

Commit and publish your changes

Before you can publish your changes (branch: master), you have to commit them to your local repository:

• Commit all changes in current working tree:

  git commit -a -m "Useful change description"

• Commit selected files:
  • Repeatedly: git add FILENAME
  • Then: git commit -m "Useful change description" (note the omitted -a)

Repeat this step as often as required. It's recommended to keep commits small (one or a few related changes only).

As soon as you decide to publish your changes you push them to your personal server-based repository like this:

git push [origin master]

The remote and branch name in square brackets are optional. You don't need the remote and branch name when you set up your local repository as described in the preceding section.

Pushing your changes back into tracked CVS repository

If you are working on branches off a CVS-tracking repository, you can export your commits from git back into CVS using git cvsexportcommit.

1. First you need to checkout a pristine CVS working-copy (or update it, if you have one already). IMPORTANT: the checkout/update must use the option -kk to avoid CVS keyword-expansion (such as $Id: Git.txt,v 1.37 2018/07/13 12:48:57 OliverBock Exp $), and must be "clean", i.e. it must not contain any local modifications. Example: assume $CVS_HOME is the directory containing the CVS working tree to push the git-changes into:

   cd $CVS_HOME
   cvs update -kk
   

2. From the git-repository, determine the 'name' (eg its SHA1) of the commit you want to export to CVS, e.g. using git log -1 if it is the most recent commit. Then (from the git-repository) do:

   git cvsexportcommit -c -w $CVS_HOME SHA1
   

which generates a patch from the named commit 'SHA1', applies it to the CVS working tree, and if it applies cleanly, commits the result to CVS. Note that your git branch should be reasonably up to date with the CVS tracking repository before exporting, in order to avoid conflicts during the export.

Available Repositories

You can find the web interface to all public/personal, shared and tracking repositories hosted at AEI Hannover here.

If you want to have your personal repository listed here as well, please contact Oliver Bock, Carsten Aulbert or Henning Fehrmann.

Project tracking repositories

Tracking repositories @ UWM:

• git://ligo-vcs.phys.uwm.edu/lal.git
• git://ligo-vcs.phys.uwm.edu/lalapps.git
• git://ligo-vcs.phys.uwm.edu/metaio.git
• git://ligo-vcs.phys.uwm.edu/pylal.git
• git://ligo-vcs.phys.uwm.edu/matapps.git
• git://ligo-vcs.phys.uwm.edu/einsteinathome.git

Further reading

Documentation

• Wiki
• Main documentation

• Google Tech Talk / Distributed SCM / Why git by Linus Torvalds (Video)
• Google Tech Talk / How to use git by Randal Schwartz (Video)
• Various screencasts on single git topics (Video)

• Tutorial
• An introduction to git-svn for Subversion/SVK users and deserters
• Git for CVS users
• Complete manual

• Linus on Git workflows

Cheat sheets

The following images are scaleable vector graphics (for unrestricted printing size) containing invaluable comman d references

• All in one: SVG image
• Extended: SVG image (front)
• Extended: SVG image (back)

Unix man pages

Check out the comprehensive pages using man git- to read more about the various commands.

Administration

• Important: new repositories should be based on gitosis only!
• Deprecated: in order to set up a new shared repository (administrators only!):
  1. Create a shared bare repository

            mkdir /pub/my-repo.git
            cd /pub/my-repo.git
            git --bare init --shared
            

  2. and take care that the directory belongs entirely to the right group. If you already have a content in a local git repository, /home/alice/myproject say, and you want to import its master branch into the new shared repository, follow this up by
     1. git --bare fetch /home/alice/myproject master:master
     2. or you add the shared repo as a remote to your existing local repo (git remote add ...) and push the content like this git push --all (--all is only needed for the initial push!)

Mirror a SVN repository (git tracking)

Create the mirror:

# on the mirror server!
mkdir mymirror.git
cd mymirror.git
git --bare init
git --bare svn init -s http://myrepo    # alternatively without "-s" if svn standard layout (trunk/branches/tags) isn't used or just a subtree is mirrored
# if you don't use "-s" you want to change the config's "[svn-remote "svn"]:fetch" value from ":refs/remotes/git-svn" to ":refs/remotes/trunk" (or whatever subtree/branch you mirror)
git --bare svn fetch

Publish the mirror (e.g. via gitosis) once:

# on the mirror server!
cd mymirror.git
git remote add tracking git@gitosis:mymirror.git
git config --unset remote.tracking.fetch
git config remote.tracking.push 'refs/remotes/*:refs/heads/*'
git push tracking

Make trunk visible via gitweb (since there is no master branch and therefore no defined HEAD) once:

# on the gitosis server!
cd mymirror.git
git symbolic-ref HEAD refs/heads/trunk

Update mirror and publish updates periodically:

# on the mirror server!
cd mymirror.git
git --bare svn fetch
git push tracking