MOLGENIS

on

GitHub

​

​

A practical how-to

by Joeri van der Velde

June 2012

updated November 2012

Before you start:

​

• Create an account on GitHub
• Install a command line Git client

​

Highly recommended:

​

• Setup username/email (see here)
• Setup SSH keys (see here when logged in)

​

The most prominent MOLGENIS repositories on GitHub are:

​

• molgenis
• molgenis_apps

​

For this introduction, we take molgenis as example and represent it by:

molgenis

The molgenis repository is updated only by selected admins and is called "blessed".

​

To create a development version for yourself: log in to GitHub, go to the molgenis repository, and click Fork.

​

The result:

​

​

molgenis

blessed

molgenis

my fork

fork

Your fork still 'lives online', and you'll need a local copy to work with. In your (Eclipse) working directory, type:

​

git clone git@github.com:MYACCOUNTNAME/molgenis.git

​

(The links for SSH and HTTPS can be found on your personal GitHub repository page)

molgenis

blessed

molgenis

my fork

fork

molgenis

my clone

clone

online

offline

Go into the directory for molgenis on your system and type

​

git status

​

It should tell you that you are working on the master branch (ignore branches for now) and there are no changes.

​

For demo purposes: create a file demo.txt and do git status again.

Git detects the new (or changed/deleted) file, and now you need to tell Git what to do with it. This is called staging a commit.

• Use git add FILENAME to add new or updated files to the next commit.
• Use git rm FILENAME to add 'the deletion' of a file to the next commit.
• Use git checkout -- FILENAME to discard any changes.

​

Save the change set in a commit to your local clone by typing:

git commit -m "I have done some work"

You can create as many commits as you want, building up a nice timeline of progress.

molgenis

blessed

molgenis

my fork

fork

molgenis

my clone

clone

online

offline

changes

commit 1

commit 2

commit 3

commit

Before you continue, make sure your remote locations are configured correctly.

​

By convention, you want your own fork to be referred as origin. (the place you cloned it from) Let's call the blessed location molgenis. List the remotes and see:

> git remote -v

molgenis git@github.com:molgenis/molgenis.git (fetch)

molgenis git@github.com:molgenis/molgenis.git (push)

origin git@github.com:MYACCOUNTNAME/molgenis.git (fetch)

origin git@github.com:MYACCOUNTNAME/molgenis.git (push)

If not: setup the remotes by removing/adding.

​

You can remove remote locations using:

git remote rm LOCATION_NAME

​

And add them as such:

git remote add origin

git@github.com:MYACCOUNTNAME/molgenis.git

​

git remote add molgenis

git@github.com:molgenis/molgenis.git

Now you can send your commits to the online fork by using:

git push origin master

"Push my currently active branch to master branch of the origin remote location"

molgenis

blessed

molgenis

my fork

fork

molgenis

my clone

push

online

offline

changes

commit 1

commit 2

commit 3

commit

Similarly, update your software (on another machine) by using

git pull origin master

"Pull updates from the master branch of the origin location to my current active branch"

molgenis

blessed

molgenis

my fork

fork

molgenis

my clone

pull

online

offline

changes

commit 1

commit 2

commit 3

commit

It is crucial that you remain in sync with the blessed repository at all times. If you are not, your code may be uncompatible to be merged back into blessed. To update from blessed:

git pull molgenis testing

molgenis

blessed

molgenis

my fork

fork

molgenis

my clone

pull

online

offline

changes

commit 1

commit 2

commit 3

commit

You now have the latest blessed version merged with your local clone. This will most likely institute many changes. The pull merge automatically creates a special kind of commit with the message:

​

Merge branch 'testing' of github.com:molgenis/molgenis

​

Using this local merge, you must update your online fork using the same push command as before.

​

We complete the roundtrip by sending out a pull request to the admins of the blessed repository, requesting our fork to be incorporated into blessed. Use the Pull Request button in the GitHub website view of your fork.

molgenis

blessed

molgenis

my fork

molgenis

my clone

pull request

online

offline

changes

commit 1

commit 2

commit 3

commit

Conflicts

There are 3 types of conflicts (git status):

1. the merge wants to delete a file that you modified
2. the merge wants to modify a file that you deleted
3. the merge wants to modify lines of code that you have also modified

​

To resolve 1. and 2. you use the commands

'git rm <the file in question>' and

'git add <the file in question>' depending on what you want to happen (remove or re-add)

​

Comodification conflicts

In case a file has been modified in the same place by both you and the merge, git will annotate the file (possibly in many places):

​

​

​

​

​

​

• Your changes are between >>>HEAD and ===.
• The incoming changes are between the === and <<<<..
• Edit the file so it says what you want, then commit as normal.

The pull request button is on the github page of your fork, at the top:

Send pull requests to another branch of molgenis. This example uses a 'testing' branch.

​

Click here to get choice of branch

Change to 'testing' here

GitHub can of course do much more. Remember Google is your friend.

​

Branching is a powerful feature which you can use to work on some unfinished side project, that would break tests when pushed to the master branch. You can also cherry-pick, blame, reset, amend, rebase, log, diff, fetch, tag.. etc :) also, learn how to merge.

​

Or how about bisect: Find by binary search the change that introduced a bug. How cool is that?