Using Git for SPECFEM

Table of Contents

• One time configurations for all repositories
  • Open a free account at GitHub
  • Configure ssh-keys for GitHub
  • Install hub
  • Download our configuration script config_repo
• One-time configuration for each repository
• Regular daily usage

One time configurations for all repositories

Open a free account at GitHub

• If you do not already have one, you will need to open a free account at https://github.com. In order to become a contributor / developer for SPECFEM you do NOT need to create any account on our Web site nor to get access rights from us, the only thing you will need is a GitHub account.

Configure ssh-keys for GitHub

• https://help.github.com/articles/generating-ssh-keys

Install hub

• Install the package called ruby using your package manager or any other suitable method (for instance on Linux Ubuntu machines you can type sudo apt-get install ruby or sudo yum install ruby or similar)

• Install the package called rake using your package manager or any other suitable method (for instance on Linux Ubuntu machines you can type sudo apt-get install rake or sudo yum install rake or similar)

• On some Linux systems (for instance Red Hat Linux) you will need to type sudo yum install rubygem-rake-compiler or similar instead to install the two above packages

• Install the package called libopenssl-ruby using your package manager or any other suitable method (for instance on Linux Ubuntu machines you can type sudo apt-get install libopenssl-ruby or sudo yum install libopenssl-ruby or similar)

• Download the package called hub:

  $ git clone https://github.com/github/hub.git
  

• Install hub somewhere in your PATH, e.g. in ~/bin:

  $ mkdir -p ~/bin
  $ cd hub
  $ rake install prefix=~/bin
  $ cd ~/bin
  $ ln -s bin/hub
  

• Permanently alias git to hub. Put it in your .bashrc. Make sure the path where you have installed hub is executable and is in your PATH.

  $ alias git='hub'
  

Download our configuration script config_repo

• Copy/paste the following script in ~/bin/config_repo

  #!/bin/bash
  # Set configuration for github.
  # Configuration is saved in .git/config
  
  ARGS=1
  if [ $# -ne $ARGS ] || [ $1 == "-help" ]
  then
    echo "usage: config_repo your_github_user_name "
    exit 0;
  fi
  
  GITHUB_USER=$1
  
  GITVERSIONMAJOR=`git --version | head -1 | cut -f 3 -d " " | cut -c 1`
  GITVERSIONMINOR=`git --version | head -1 | cut -f 3 -d " " | cut -c 3`
  
  if [[ "$GITVERSIONMAJOR" -eq 0 || ("$GITVERSIONMAJOR" -eq 1 && "$GITVERSIONMINOR" -le 7) ]]; then
    echo "git version >= 1.8 is needed for the scripts to work, but you have"
    git --version
    echo "please install git version >= 1.8 and try again"
    exit -1
  fi
  
  git config --global url."https://".insteadOf git:// 
  git config branch.master.remote origin
  git config branch.master.merge master
  git config branch.master.pushremote $GITHUB_USER
  git config branch.devel.remote origin
  git config branch.devel.merge devel
  git config branch.devel.pushremote $GITHUB_USER
  git config push.default current
  git remote set-head origin devel
  

• Make it executable

  $ chmod u+x ~/bin/config_repo
  

One-time configuration for each repository

• Clone the repository on your machine (VERY IMPORTANT: in what follows the example is given for specfem3d, but you can replace that with specfem2d or specfem3d_globe if you want to use any of the other two packages)

  $ git clone geodynamics/specfem3d
  

• Checkout the devel branch

  $ cd specfem3d
  $ git checkout -b devel origin/devel
  

• Call our configuration script

  $ config_repo your_github_name
  

• If (and only if) calling our configuration script gives you an error message telling you that you have an old version of Git and that you need to install Git version 1.8 or above instead, you can do this to install Git version 1.8 (and then try to run the configuration script again):

First (that is optional on some systems) you will need the following packages to be installed (they might already be installed, they are fairly common):

sudo yum install curl-devel expat-devel gettext-devel openssl-devel zlib-devel

or

sudo apt-get install libcurl4-gnutls-dev libexpat1-dev gettext libz-dev libssl-dev ssh expat zlib1g zlib1g-dev tk python

and then, to install the new version of Git from its source code, type this:

cd $HOME

mkdir bin/git src

cd src

git clone git://git.kernel.org/pub/scm/git/git.git

sudo apt-get remove git-core

cd git

make prefix=/usr/local all

sudo make install prefix=/usr/local

• create a fork (a copy of the repository on your GitHub account) (do this only once, i.e. if you are using several computers, each with a copy of the code, then run "git fork" on the first machine only, no need to do it when you create copies on the other machines later)

  $ git fork
  

Regular daily usage

• update your copy of the repository

  $ git pull
  

• make some changes to any file you want using your favorite editor (in the line below we use vi as an example)

  $ vi some_file.f90
  

• commit your changes locally, adding a very short message (one line) explaining what you have changed

  $ git commit -a -m "Explain your commit"
  

• (optional) if you want to check what has changed (and thus what will be committed) before typing the git commit above, you can type one or both of these two commands:

  $ git status -s
  $ git diff
  

• push your changes to your GitHub fork

  $ git push
  

• Create a pull-request to get your changes into the main repository (this is needed only once for each change; if you are fixing an existing change after receiving an error message from our BuildBot code-consistency checking system, you need the "git push" above again but you do NOT need to create a pull request a second time)

  $ git pull-request
  

Note (optional): It is not strictly necessary to create a pull request for every commit you make if you do not want to, you can safely submit pull requests after making a few commits instead if you prefer. However, it also does not hurt to do so.