Gromacs

Git Tutorial

    Version as of 11:58, 31 Oct 2014

    to this version.

    Return to Version archive.

    View current version

    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

    Novice

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

    git clone git://git.gromacs.org/gromacs.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.0 + 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-0-patches origin/release-4-0-patches

    This will create a local tracked branch (named release-4-0-patches), which follow the release-4-0-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 verision section).

    Take a look at the changes

    a nice graphical interface to view changes is

    gitk

    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.

    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/

    ...........

    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)

    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.

    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

    Bugfixes 

    The following are the recommended steps to submitting bug-fixes. 

    1. All bug-fixes are should be committed to the release branch first (if one accidentally commits to the "master" branch - one can cherry-pick it to the release  branch)
    2. If it is a workaround which shouldn't be merged into master this should be noted in the commit message. One should do all next steps!
    3. Next one checks that the release branch doesn't contain any unmerged commits, to make sure not to merge changes which shouldn't be merged.
      git log master..release-4-5-patches
      
    4. 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)
    5. Next one merges the release branch into the "master" branch   
      git checkout master; git merge release-4-5-patches
    6. If the release branch contained one or more workarounds which shouldn't be included into the "master" branch one reverts those with
    7. git revert -n <commit>; git commit --amend 
       

     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

     

     

    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.


    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 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"

    Page last modified 18:43, 30 Jul 2010 by rossen