Skip to content

Git Tutorial for SHiP

Jump to bottom
Oliver Lantwin edited this page Feb 19, 2019 · 3 revisions

Table of Contents

This page should allow new Git users to get started with the SHiP software, and describes the workflow for accessing and contributing SHiP code.

A Git primer (skip if you're a Git guru)

Git is a version control system (VCS) used to track the changes to a software package over time. It is very different from other VCSs, and it is by far the best one.

If you are not very familiar with Git already and even if you already know CVS or Subversion, we strongly suggest you to follow this tutorial.

The official repositories for the SHiP software are hosted on GitHub. The GitHub repositories are just standard Git repositories, GitHub just makes it easier for people to collaborate with Git.

Getting started with GitHub

Creating and setting up your GitHub account (skip if you have a GitHub account)

To be done once.

Follow these instructions: https://github.com/join, and be sure to select the free plan.

Then, upload your ssh key to GitHub, so that GitHub can identify you when you push some modifications.

Cloning the official SHiP software repository on GitHub

You won't be allowed to "push" your modifications to the official repositories for the SHiP software. Still, you will want to contribute code at some point. The solution is to clone (we say "fork") the official repository on your GitHub account, so that you have your own version of the repository hosted on GitHub. You will then push modifications from your local machine to your fork on GitHub. Then, you will use GitHub to ask the SHiP software administrators to pull these modifications from your fork. A tutorial showing how to do this is provided here.

But first, let us fork the official SHiP software repository FairShip. To do that, sign in your GitHub account and go to FairShip on GitHub. Then click on the Fork button at the top right of the page. You should be redirected to your own version of the repository, which is at this point identical to the official version of the repository.

Setting up Git on your AFS or local account

To be done once.

Set your name:

$ git config --global user.name "Mona Lisa"

Set your email:

$ git config --global user.email "email@example.com"

It is recommended that you also set the following options:

$ git config --global core.whitespace trailing-space,space-before-tab

Getting the code

Cloning your FairShip repository to lxplus or local machine

This section explains how to obtain a clone of the SHiP repository on your local machine. You will work locally with this repository and when ready, you will be able to push commits from this repository to your GitHub repository.

To be done every time you want to set up a new local area, e.g. on your AFS account.

Go to a directory of your choice, and type (replace USER_NAME by your user name)

$ git clone git@github.com:USER_NAME/FairShip.git
$ cd FairShip

Check that you have files in your working directory:

$ ls

Print the list of remote repositories, with some additional information:

$ git remote -v
origin  git@github.com:USER_NAME/FairShip.git (fetch)
origin  git@github.com:USER_NAME/FairShip.git (push)

This printout means that you have one remote repository called origin here, which is the GitHub repository you cloned. You can both fetch from (retrieve new commits from) and push to (send new commits to) the origin repository.

Check the commit history in your newly created local repository

$ git log

At the top, you should see the commit to which two branches are pointing to:

master
origin/master

master is the main local branch, and origin/master is the main branch on the origin repository. In both repositories, the HEAD pointer indicates the current branch, and it should be the master branch. The version of the code in your local working directory corresponds to the version of the code from the commit that is pointed to by the HEAD.

Refreshing your version of the code

When people contribute code to the official FairShip repository on GitHub (we'll see how to do that below), your fork on GitHub and your local repositories remain untouched and thus become outdated. This section explains how to update your versions of the FairShip repository so that you can get the code from other people.

Adding the official FairShip repository as a remote

To be done once for each local area.

Let us add the official FairShip repository on GitHub as a remote. Go to the official FairSHip repository on GitHub. On the right of the page, clone URLs are provided. Since we just want to get code from there, we will connect to this remote repository using the https protocol. Click on HTTPS and copy the URL in the box. Paste it as in the following shell command line:

$ git remote add official https://github.com/ShipSoft/FairShip.git

Check the results:

$ git remote -v
official        https://github.com/ShipSoft/FairShip.git (push)
official        https://github.com/ShipSoft/FairShip.git (fetch)
origin  git@github.com:USER_NAME/FairShip.git (fetch)
origin  git@github.com:USER_NAME/FairShip.git (push)

Getting new code from the official FairShip repository

The ensemble of Git commits in your local repository form a directed acyclic graph. That's what geeks say - normal people say a tree. Your HEAD is currently pointing to the master branch that is itself pointing to a given commit. As long as you don't change branch, the code in your working directory doesn't change.

Now, it could be that the commit tree on the official FairShip repository has changed. Maybe some branches have grown or new branches have been added. What we want to do now is to get this information in our local tree. To do that, issue the following command (remember that official is the name of the official FairShip repository). Have no fear, your working directory is not going to change.

$ git fetch official

Git should tell you what it does. At least, it will add remote brances from the official repository, such as this one:

* [new branch]      master     -> official/master

This means that a "remote branch" has been created in your local repository. This remote branch is called official/master, and points to the same commit as the master branch in the official repository.

List all branches in your local repository:

$ git branch -a
* master
  remotes/official/master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

The star indicates the branch pointed to by the HEAD, that is the current branch. Remote branches are listed as well. There are two remote master branches. The first is in the origin repository that was cloned to create the local directory. The other one is in the official repository. These master branches will usually not point to the same commit. Let's see which commit is indicated by each branch:

$ git branch -a -v
* master                  ef8f4ac fixed missing field for horizontal connections
  remotes/official/master efc88cc added weight as data member
  remotes/origin/HEAD     -> origin/master
  remotes/origin/master   ef8f4ac fixed missing field for horizontal connections

We see that the local master and the origin/master point to the same commit. It should be the case because you just cloned. But the official/master points to another commit (a later one).

Let's include the modifications on the official/master to our local master. This is done by merging the official/master branch into the local master. Make sure you are on the master branch. If not, go to this branch:

$ git checkout master

Now merge official/master into master:

$ git merge official/master

Check the situation:

$ git log
$ git branch -a -v
* master                  2826522 [ahead 9] Merge pull request #2 from dyk/master
  remotes/official/master 2826522 Merge pull request #2 from dyk/master
  remotes/origin/HEAD     -> origin/master
  remotes/origin/master   ef8f4ac fixed missing field for horizontal connections

master has moved to official/master and origin/master, your own fork on github, is now late.

Let's get more information about that:

$ git remote show origin
* remote origin
  Fetch URL: git@github.com:ShipSoft/FairShip.git
  Push  URL: git@github.com:ShipSoft/FairShip.git
  HEAD branch: master
  Remote branch:
    master tracked
  Local branch configured for 'git pull':
    master merges with remote master
  Local ref configured for 'git push':
    master pushes to master (fast-forwardable)

$ git remote show official
* remote official
  Fetch URL: https://github.com/HEP-FCC/FCCSW.git
  Push  URL: https://github.com/HEP-FCC/FCCSW.git
  HEAD branch: master
  Remote branch:
    master tracked
  Local ref configured for 'git push':
    master pushes to master (up to date)

We see that our master branch tracks the modifications in the master branch of both remote repositories. The local master is up to date with respect to official/master, meaning these two branches point to the same commit. However, origin/master points to a later commit than the local master.

To update origin/master, do:

$ git push origin master

Check the results:

$ git branch -a -v 
$ git remote show origin
-- use the web interface of GitHub to see that origin/master has been updated correctly --

Contributing code

In this section, you will add a simple text file to this directory, and contribute this text file to the official FairShip repository.

Let's first create a branch for these modifications:

$ git checkout -b git_test
$ git branch
* git_test
  master

Now let's create the text file in the working directory:

$ mkdir YOUR_USER_NAME
$ cd YOUR_USER_NAME
$ echo "my text contents" > my_file.txt
$ cat my_file.txt
my text contents

Then, let's commit the new directory with its text file to the git_test branch

$ git add .  # add the current directory (YOUR_USER_NAME)
$ git commit -m 'testing git'
$ git log

Now that the change has been committed to the local repository, we need to push it to your GitHub fork:

$ git push origin git_test

Go to your FairShip repository on GitHub, and select the new branch in the drop-down menu. You should see the new file there.

Finally, click on pull request, and wait for one of the FairShip administrators to approve it. You will be notified by mail.

Congratulations!

Summary

Our code development workflow

You will be using (at least) 3 versions of the FairShip repository:

  1. The official FairShip on GitHub
  2. Your fork of FairShip on GitHub
  3. Your local repository on AFS or your local disk

The repositories 1 and 2 are added as remote to the repository 3.

To get new code:

  • fetch it from 1 to 3
  • push it from 3 to 2

To contribute new code:

  • push it from 3 to 2
  • create a pull request from 2 to 1

Recommendations

Please always follow the recommendations below:

  • feel free to commit often to your local repository, but do not create pull request for small incremental changes.

  • if you're working on a given topic, always create a branch for it, e.g. pythia_interface. You may commit many times to this branch in your local repository. When you have something solid (at the very least the code must compile) or when somebody needs your code, create a pull request to the official FairShip repository.

  • always provide a meaningful commit comment.

  • commit comments should be like as below, so that they show up correctly e.g. when people do git log:

      first version of a pythia interface # this line should be a short 1 liner

  Here, you may write a few more lines if needed

Need help?

Feel free to drop a mail to ship-software at CERN, and we'll be happy to help you :-) !

Acknowledgement

Original text by Colin Bernet.

Clone this wiki locally