Git Tutorial

Stable version

Most likely you want to work with the stable version (version 4.5 + all the bugfixes) instead of the developer version. The best way to do so, is to create a tracked branch. Enter your gromacs dir and execute

git checkout --track -b release-4-5-patches origin/release-4-5-patches

This will create a local tracked branch (named release-4-5-patches), which follow the release-4-5-patches branch of the origin repository. For more infos about branches see the Normal User section.

Updating

From time to time you should update your repository by running

git pull

which will download all the changes from the origin destination (where you cloned from before, most likely git://git.gromacs.org/gromacs) and merge them into your working copy. This should work without any problem when working with a unchanged version of gromacs. It also works branch wise if you are on a tracked branch (see stable version section).

Status

You can easily find out which files don't belong to repository with

git status

in most cases you will see a lot of object files (.o) and stamp files from the build process.

# On branch release-4-0-patches
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#       src/contrib/.deps/
#       src/gmxlib/.deps/
#       src/gmxlib/gmx_blas/.deps/
#       src/gmxlib/gmx_lapack/.deps/
#       src/gmxlib/nonbonded/.deps/

...........

Adding your own stuff

To add some extra stuff to your cloned gromacs repository, just copy the files into your gromacs dir and execute

git add file1 file2 ...

after that you can check the status

git status

the message should contain something like:

# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       new file:   file1
#

now you are ready to commit

git commit -m "Added my own stuff"

verify the result with

git log -1

which should tell something like:

commit 7c92c1f9bcd87d05e8a43757cdd845d7ba76a526
Author: user <user@linux.(none)>
Date:   Thu Jun 18 10:54:41 2009 +0200

    Added my own stuff

(if you don't like what it says at author, see the Tips & Tricks Section)

Updating

This works in the same way as before, just run

git pull

as pull is the combined operation out of fetch and merge, your repository will include an automatically commit message (use "git log" to view it) like this:

commit 95297300261032063632c9fe77578133cc40a6a7
Merge: 4d66c61... e640e89...
Author: user <user@linux.(none)>
Date:   Fri Jun 19 09:48:19 2009 +0200

    Merge branch 'master' of git://git.gromacs.org/gromacs

To understand this effect, we have to take a look at branches.

Keeping your version in sync at different places

Due to the fact that git is distributed version managment system you can simply clone the gromacs version with your own changes to a new location

git clone path/to/yourgromacs   another_repo

git is smart enough to clone over ssh

git clone ssh://somecomputer/~/path/to/gromacs     repo_here

(~ is as usual your home). If you have done changes in location1 you can use pull from location2 to get them

location1> git pull location2

The "opposite" of pull is push. This make it possible to push your changes to another place

location2> git push location1

But attention, git will never touch the remote working dir, so you have to execute:

location1> git checkout HEAD

in location1, to checkout the newest revsion, called HEAD.

Merging bug fixes into development branches 

The following are the recommended steps for incorporating bug fixes into development branches. 

1. We assume all bug-fixes are committed to the release branch (if one accidentally commits to the "master" branch - one can cherry-pick it to the release  branch) and that we have a fresh copy of both it and master:
   

   git checkout -t origin/master
   git checkout -t origin/release-4-5-patches

2. Next one looks in the release branch for any unmerged commits, to make sure not to merge changes which shouldn't be merged. 

   git log master..release-4-5-patches
   

3. Whether a commit might not be merged should be noted in the commit message. If it does contain unmerged commits, one checks that it is clear whether the commits are supposed to be merged or not (and asks the author if it is not clear).
4. Next one merges the release branch into the "master" branch

   git checkout master
   git merge release-4-5-patches

5. If the release branch contained one or more workarounds which shouldn't be included into the "master" branch one reverts those with

   git revert -n <commit>
   git commit --amend

6. Finally, push the merged master repository to the server

   git push

 If one has only commits in the release branch which shouldn't be merged into master one can do:

git merge -s ours release-4-5-patches

Private Branches

Gerrit allows to have private branches (refs), for which you can set own permssions, see Admin/Project/Access

To use your private refs more conviently the following block should be added to .git/config

[remote "private"]
        fetch = +refs/private/USER/*:refs/remotes/private_USER/*
        url = ssh://USER@gerrit.gromacs.org:29418/gromacs
        push = refs/heads/private_USER/*:refs/private/USER/*

After that do a

git pull private

and create a tracked branch

git checkout -b BRANCH --track private_USER/BRANCH

Remeber to replace BRANCH and USER in the above commands.

Git behind a proxy

git knows about http_proxy environment variable, but tunneling the git procotoll is sliently more complicated:

• install socat
• create a script git-proxy.sh containing (replace your_proxy and your_proxyport):

#!/bin/bash

socat STDIO PROXY:your_proxy:$1:$2,proxyport=your_proxyport

• tell git to use git-proxy.sh as proxy command

export GIT_PROXY_COMMAND=git-proxy.sh

Your own gromacs mirror

Create a gromacs mirror for your group is very easy. git (>=1.6) has already everything onboard, just run:

git clone --mirror git://git.gromacs.org/gromacs

That's it, the only thing left to do is to create a cronjob running

git fetch

every hour. To give the mirror a nice small http interface run:

git instaweb

(you will need lighttpd for that). Now the http interface can be seen at:

http://localhost:1234 and http://your_hostname:1234

your whole intranet can use this mirror to clone with

git clone http://your_hostname:1234

In nearly the same way the mirror on repo.or.cz was created.

Introduce yourself to git

git has a global and repository wise place to save personal setting

git config --global user.name "Superman"

git config --global user.email "kent@metropolis-press.com"

leave away --global to make a repository wide change.

Colors

are nice and useful, so enable them:

git config --global color.ui "auto"