Git Tutorial

    This tutorial should give an overview of how to use git at the example of gromacs.

    The number of useful git commands increases exponentially with the amount of changes you have to manage, that is why we will part the users in 4 groups:

    • Novice - you are just using the orginal gromacs version without your own changes
    • Normal User - you are using the original gromacs with a handful changes
    • Power User - you are using your own gromacs version with major changes
    • Developer - you are using your own gromacs version, but it is the original gromacs version


    Getting your own copy of the gromacs repository is very simple, just run:

    git clone git://

    (If you have problems connecting, because you are behind a proxy, see the Tips & Tricks section.)

    The clone command will also checkout the most recent (developer) version for you. The directory created contains two parts

    • the git repository - the .git dir
    • your working copy - the rest of the files and dirs (missing when adding the --no-checkout option)

    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.


    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:// 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).

    Take a look at the changes

    a nice graphical interface to view changes is


    but the main (summary) informations about the changes you can see with

    git log

    To see the changes in the source code (the actual patch) take a look at the Normal User section.


    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/


    Normal User

    Please read und understand the Novice section first.

    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)


    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://

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


    Branches come completely natural in git (not like in cvs, where you to create them). Let's you make one commit in location1 and other commit in location2, so both location locally follow the trunc, but seen on the global scale the repository was branched. But this is nothing bad, "git pull" will just merge the two branches to a new trunc. This is one of the stength of git, like Towalds Linus says: "Merging should be easy not branching".

    Merge vs. Rebase

    As said before git pull internally does something like

    git fetch

    git merge FETCH_HEAD

    Power User

    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://
            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.

    Tips & Tricks

    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 containing (replace your_proxy and your_proxyport):


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

    • tell git to use as proxy command


    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://

    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 was created.

    Introduce yourself to git

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

    git config --global "Superman"

    git config --global ""

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


    are nice and useful, so enable them:

    git config --global color.ui "auto"

    Page last modified 13:51, 28 Jan 2013 by rossen