Gromacs

Basic Git Usage

    Version as of 15:21, 20 Nov 2017

    to this version.

    Return to Version archive.

    View current version

    Git is a very powerful source code management system. Here, we will quite deliberately only cover the basic stuff necessary for Gromacs development and try to keep it simple. If you want to learn more, including how to set up your own repository for a non-gromacs project, consult the official git documentation instead. 

    Getting Git

    Just as CVS, Git is a (newer) program you need to have installed to be able to use it. Check if you have it with the command "which git". Many modern Linux systems already come with it preinstalled, or you might be able to get it in a single step with a command like "sudo apt-get install git-core". Otherwise, you can find both binaries and source code from the official git site. For reference, the Gromacs Git server currently runs version 1.6.3.2, but you should be able to use interact with it using older versions too. 

    Understanding servers & repositories

    The master Gromacs source code repository is available from the server git.gromacs.org, and there will soon be a public read-only backup available at git2.gromacs.org that is updated automatically (useful if the main server is unreachable for some reason). On both of these servers, there are a number of independent repositories. If you are used to CVS, a Git repository roughly corresponds to a CVS module. Each repository can have multiple branches. On the main server we have at least the repositories:

    • gromacs.git - The Gromacs source code (corresponds to the old CVS 'gmx' module)
    • manual.git - The Gromacs manual latex source
    • regressiontests.git - A suite of regression tests that (old 'gmxtest' module)
    • libxdrfile.git - A separate library to read/write our XDR compressed data files

    However, in contrast to CVS you don't interact directly with our repositories when you modify code! When you "check out", you really make a complete clone of the repository, and then interact with our own copy. You can even create arbitrary local branches that track some other branch in our repository. Developers with write permission can then separately "push" their changes to the main repository, after which they will show up to everybody. Similarly, you "pull" to get your local repository synchronized with a remote one. The beauty of this is that anybody can create a public repository where they share their Gromacs changes, and you call also "pull" in modifications from multiple other repositories.

    In addition to the "official" Gromacs repositories, many of the core developers will also have their own public repository available on the git.gromacs.org server, which you access in a slightly different way (more below). It is also straightforward to set up your own public repository at a place like github.com (free for open source).

    Checking out a new repository

    To make a local copy of a repository, you use the command "git clone" followed by a specification of a repository. To do this anonymously with read-only access you just write

    git clone git://git.gromacs.org/gromacs.git

    As alternatives you can use either

    git clone https://gerrit.gromacs.org/p/gromacs
    

    or

    git clone https://github.com/gromacs/gromacs.git

    Making a well-behaved commit message

    • Git commit messages should follow a certain pattern in order to make various automated tools work well displaying these messages. The first line should be no longer than 56 characters. A blank line should follow and subsequent lines should be no longer than 73 characters. You can configure git commit to launch an editor to make this easier for you to do.
    • The commit message serves to establish what happened and provide some context for why. The primary purposes are to allow the reviewers to quickly understand what the commit is about, and later when people want to understand why code is the way it is, then can find some information there.
    • Commentary about the review process does not belong in the commit message.
    • If the commit deals with a Redmine issue xxx, the commit message should include "Fixes #xxx", or "Refs #xxx" (as appropriate).
    • When you submit your patch to Gerrit, it will get refused unless you have installed the appropriate commit hook described there.
    Page last modified 15:05, 28 Feb 2013 by mabraham