GitHub workflow in a nutshell

In order to work with Clara2 and develop the code, you need to use GitHub.

There are several tutorials on how to use GitHub addressing beginners to experts.

In case you are a beginner, this workflow in a nutshell will walk you through the steps necessairy to get working.

---

Set up your repository

1. First of all you will need a GitHub account and set up the git configuration in your working environement.

2. Create key-pair to use ssh.

3. Fork Clara2 on GitHub, by clicking Fork on the upper right corner and choosing your account.

4. create local copy on your machine:

git clone git@github.com:<YourUserName>/clara2.git

5. go into the directory of the new repository

cd clara2

6. add the ComputationalRadiationPhysics/clara2 respository for updates

git remote add mainline git@github.com:ComputationalRadiationPhysics/clara2.git

7. switch to our (now your) dev branch to start

git checkout dev

General work

1. Check what branches are available:

git branch

2. Choose a specific branch

git checkout <branchName>

Start your own branch to work in

1. go to dev branch

git checkout dev

2. create your new branch and check it out

git checkout -b <nameOfNewBranch>

3. work on the code: change, delete and add files

4. Check status of your branch

git status

5. add changes to your branch

git add <yourChangedFiles>

6. commit your changes to your local branch (on your machine)

git commit

this requires that you specified an editor beforehand

for example set up emacs in your ~/.profile

export EDITOR=emacs

7. update your repoitory with the changes pushed to our dev branch

git pull --rebase mainline dev

Bring your changes to GitHub

1. push your local branch copy to your GitHub profile

git push -u origin <nameOfYourBranch>

2. Go to github.com and open a pull request.

always push to our dev branch, never to the master branch (default)

3. In case improvments are required, update your local copy and push the changes to your GitHub profile again until your pull request is accepted.

4. If you want, delete your brach localy and on your GitHub profile.

# delete remote branch
git push origin --delete <branchName>
# delete local branch
git branch -D <branchName>

5. When you added many branches and deleted them both on the remote origin as well as the local repository, the local reposity still remembers the no longer existing branches in autocomplete. In order to update the autocomplete list, do:

git fetch --prune origin

Generate clean pull requests

In order to make clean pull requests, that do not depend on your every day commits, but combine commits in a meaningfull way, you can squash your commits.

1. Have a look at you commits, starting from the branching. A short representation of your commits can be generated via:

git log --oneline --graph --decorate --first-parent

2. Then, you can rebase your branch starting from the branching point (here, as an axample e1ba799).

git rebase -i e1ba799

The flag -i stands for interactive.

3. Your favorit editor is opend and lets you reorder your pull requests. By replacing p or pick with s or squash you can combine several commits to one.

4. After saving, you run through the update process of the commit massages of your newly combined commits. Save each message untill no more commits are left.

5. Then you can push the reorderd branch to your repository.

git push -u -f origin NameOfBranch

The force flag -f is essential since the order of your previous commits will be changed.

For more information, see http://davidwalsh.name/squash-commits-git.

Checkout other's pull-request for testing

Assume that you are the assigned developer to verify a proposed pull-request from another developer. You can read the changes code lines and mark mistakes directly on GitHub. But sometimes this is not enough and you need to run the new code yourself. You could create a new repository pointing to the Clara repository of the other developer, check out his/her code, compile and test it and than delete everything. But there is a simpler way to access the code of a pull-request directly. By:

git fetch mainline refs/pull/PULLREQUEST_NUMBER/head:NAME_OF_NEW_LOCAL_BRANCH
get checkout NAME_OF_NEW_LOCAL_BRANCH

you check out the code of the pull request PULLREQUEST_NUMBER and put it in a new local branch named NAME_OF_NEW_LOCAL_BRANCH. Then you can run the code of the pull request and delete the branch if you are done. I found this usefull approach here.