Why bother with version control systems?

What is ?

• git is a fast, distributed version control software
• Almost all operations are local (i.e. fast)
• Very well documented online and on the commandline
• Distributed: every user has a copy of the entire project repository

• Not just for large software or project groups
  • personal configuration files
  • papers, documents (works best if plain text)
• Allows and encourages easy branching
  • e.g. experiment with new features, bug fixes in your code
  • merging is easy
• Most open-source software projects are now developed using git

(inspired by C. Linstead)

Commits and branches

What is GitLab?

• Open-source platform to host git repositories
• Like GitHub but non-commercial and can be self-hosted
• Gives advice/documentation for most functionalities
• Personal and group (e.g. SWIM group) repositories

Features

• Repository management
• Merge requests and code reviews
• Issue tracking
• Activity feeds and wikis

PIK’s GitLab

• https://gitlab.pik-potsdam.de
• Documentation by Ciron Linstead (and a presentation)
• Fully functional community edition

The SWIM group

Fully functional minimal test project

• The Blankenstein (Saale) catchment, ~1000km²
• 2 subcatchments, 10 subbasins, 185 hydrotopes
• syncronised with the test project of m.swim

code/
docs/
project/
    input/
      blank.bsn
      blank.str
      ...
    output/

Flexible landuse cover classes

• rather than 15 static classes, flexible number
• replacing cntab.dat for *.lut file

A more convenient Makefile

# executable with debug flags using gfortran (as before)
make
make swim
# speed-optimised executable using gfortran
make fast
# like fast but with the cluster Intel ifort compiler
make cluster

• shorter and more flexible
• some errors/warnings removed, more cleaning needed

Single .sub, .rte, .gw files to tables

• combined single files into simple tables
• b3SubFiles switch in .bsn file for transition

input/
  Sub/
    groundwater.tab
    subbasin.tab
    routing.tab

Work-in-progress: Full documentation in Latex

• docs/ contains a latex project of new developments
• The SWIM Manual (Krysanova et al., 2000) needs to be translated from Word to latex (started)

code/
docs/
  figures/
  CHANGES_SWIM_2015-11.txt
  SWIM_new_developments_documentation.pdf
  SWIM_new_developments_documentation.tex

Methods

Record issues

• filing an issue to describe a problem or a feature on GitLab
• fast and uncomplicated
• ensures the problem is not forgotten
• merge requests can later be added to the issue

Prerequisites

• git installed on the commandline (e.g. cluster console)
• a local folder to keep source code repositories
  • e.g. source/
• access to GitLab
• your SSH key uploaded to GitLab
  • top right icon > settings > SSH keys
  • copy/past output of cat ~/.ssh/*.pub
• Fork the swim/swim repository

Getting and creating a repository

Copy/download an existing one

git clone <path or url>
git clone https://gitlab.pik-potsdam.de/swim/swim.git

Creating a new (local) repository

mkdir <your name>s_test
cd <your name>s_test
git init

Inspection commands and help

git status -h    # show current changes and branch
git log --help   # browse history
git diff -h      # show code changes
git checkout -h  # switch branches or restore files
gitk &           # visual log browser

• help is available for every git command via -h (short) and --help (full help)

Recording changes

# stage files
git add <file path> <file path> ...
git commit -m 'A message describing the change.'
# or commit all changes in working directory
git commit -a -m 'A message describing all changes.'

• only recorded in own clone of repository
• Undoing commits

# without removing changes
git reset HEAD~1
# with changes discarded (careful!)
git reset --hard HEAD~1

- file status - .gitignore file

Branches

git branch -a               # show all branches incl. remote
git checkout <branch>       # switch branch
git checkout -b <new name>  # create and checkout new branch
git merge <other branch>    # merge other branch into current

Creating a new repository in GitLab

• Create New Project from user home
  • call it <your name>s_test
• Then link the local repository and push your project

git remote add origin git@gitlab.pik-potsdam.de:wortmann/michels_test.git
git push -u origin master

Linking with online repositories

• A ‘remote’ is a reference to a repository URL/path
• Every branch may be connected to any remote branch

# show all remotes setup
git remote -v
# add any remote, e.g. your fork or the trunk
git remote add <remote name> <url>
# get updates without changing files
git fetch <remote name>
# get updates and merge/update files
git pull <remote name> <remote branch>
# push to default remote branch
git push
# explicit for non-default branches
git push <remote name> <remote branch>

Merge requests

1. Pull latest trunk version
2. Create new branch
3. Make and commit changes
4. Push new branch to fork
5. Submit merge request

1. Pull latest trunk version

git checkout develop
git pull trunk develop

-> for testing, fork your neighbours test project, clone it and add the ‘trunk’ remote

2. Create new branch

git checkout -b mynewfeature

3. Make and commit changes

e.g.

echo my changes > newfile.f90
git add newfile.f90
git commit -m 'Added my changes.'

• don’t forget to implement and test changes in Blankenstein project
• as many commits possible as needed

4. Push new branch to fork

git push fork mynewfeature

> remote:
> remote: To create a merge request for mynewfeature, visit:
> remote:  https://gitlab.pik-potsdam.de/wortmann/swim/merge_requests/new?merge_request%5Bsource_branch%5D=mynewfeature
> remote:
> To gitlab.pik-potsdam.de:wortmann/swim.git

5. Submit merge request

Testing someone else’s merge request

Checkout merge request branch

git fetch git@gitlab.pik-potsdam.de:liersch/swim.git flex_lulc
git checkout -b liersch/swim-flex_lulc FETCH_HEAD

Compare differences to other branch or commit

git diff master --stat
git diff master
git diff HEAD~1  # or ea03d475ded1547
git diff master <file path>

(GitLab will remind you what to do)

Conclusions

Coding conventions

• formatting, naming conventions, function layout
• e.g. like PISM, CCLM or the European Standards for Writing and Documenting Exchangeable Fortran 90 Code
• increases code legibility and clarity
• reduces need for documentation
• reduces time to implement new features
• guidelines to tidy up SWIM
• should be precise and enforceable, not opinionated

An example