Skip to content

Using Git for SPECFEM

Jump to bottom Edit New page
Daniel Peter edited this page Nov 9, 2022 · 52 revisions

Table of Contents

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

Make sure your version of Git is fine

You need to have a version of Git greater or equal to 1.8, thus type:

    $ git --version

and if the version number displayed is 1.8 or greater everything is OK and you can skip the rest of this paragraph.

On relatively recent machines that should always be the case; otherwise if not you need to install a more recent version by doing this: first you will need the following packages to be installed (that is optional on some systems because they might already be installed, they are fairly common; if so, the commands below are safe to type anyway and will just tell you that the packages are already installed on your system):

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

Install 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 SPECFEM/specfem3d

  • Checkout the devel branch

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

  • Call our configuration script (replace "your_github_name" with your GitHub name, i.e., with your login on the GitHub Web site)

    $ config_repo your_github_name

  • create or update a fork, that is, a copy of the repository on your GitHub account. If you are using several computers (a desktop, your laptop etc.), each with a copy of the code, you need to type this on each machine; the first one will create a copy on GitHub, and all the others on other machines will make your local version aware of the existing copy on GitHub

    $ git fork

Regular daily usage

  • update your copy of the repository

    $ git pull

  • if you get conflicts when doing so (i.e. if local changes you have made conflict with changes made by others on the same line of the same file of the source code), a powerful way of resolving them is to type this: (meld needs to be installed on your system; if it is not, you can install it with apt-get install meld or similar)

    $ git mergetool --tool=meld

  • 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; it is recommended to do a git pull right before that in order to make sure that your local copy is up-to-date

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

  • if you get conflicts when committing your changes (i.e. if your changes conflict with changes made by others on the same line of the same file of the source code), a powerful way of resolving them is to type this: (meld needs to be installed on your system; if it is not, you can install it with apt-get install meld or similar)

    $ git mergetool --tool=meld

  • (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; it is recommended to do a git pull right before that in order to make sure that your local copy is up-to-date

    $ git pull ; 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); it is recommended to do a git pull right before that in order to make sure that your local copy is up-to-date

    $ git pull ; 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.

Development wiki for SPECFEM3D

Development wiki

User manual

Clone this wiki locally