Branches

The EGSnrc project adopts a workflow which is very similar the widely used "git flow" model, with a master branch, a develop branch, and any number of temporary branches to implement new features or fix issues. (There is also a separate gh-pages branch which holds the files for the EGSnrc website.)

In git, a branch is simply a label used as a convenient mnemonic for a particular commit number (see for yourself in the .git/refs/heads directory). Hence creating or modifying a branch is a very lightweight operation: it only involves updating a commit number in a file in .git/refs/heads. Since each commit in turn points to its parent commit, each defined label links to a specific history of commits; so by extension these labels are called branches.

The master branch

This is the default branch of the EGSnrc project, the one considered stable. This is the default branch when cloning the repository or downloading the zipped archive. The branch does not change between releases, except for bug fixes considered serious enough to be integrated right away. About once a year, the master branch is updated with the latest code developments and is tagged as a "release". This branch is protected, so you cannot push to this branch directly and you should not open a pull request against master.

The develop branch

This is the development branch of the EGSnrc, where latest features and bug fixes are integrated on a continuous basis. This branch is a testing ground for the next release, so we encourage you to work off this branch. While we strive to keep this branch as stable as possible, there could be occasional forced rewrites to the this branch's commit history should problems be detected. About once a year, the develop branch is merged into master and this is tagged as a "release". You may open pull requests against develop. To use the latest features of EGSnrc, clone the repositry and checkout the develop branch before configuring EGSnrc:

git clone https://github.com/nrc-cnrc/EGSnrc.git
git checkout develop

Normally, changes to the develop branch occur via pull requests to allow code review and discussion before changes are merged in.

The feature branches

At any time there may be a number temporary branches in the EGSnrc project. These are used to implement new features or bug fixes. These branches are completely unstable, meaning that commits on such branch may be squashed, overwritten, removed, etc. This means you should not rely on references to any such commits as being permanent. When a feature branch is deemed ready, its commit history is cleaned up, and it is moved to or merged into develop. The reference to the temporary branch is then removed. You may open pull requests against a feature branch if you are actively involved in the development of this branch.

It is good practice to implement your changes on a feature branch, based on an up-to-date develop branch:

git clone https://github.com/nrc-cnrc/EGSnrc.git
git checkout -b feature-x develop
# (commit your changes...)
git push origin feature-x

When the branch feature branch is ready for integration, you should clean up the commit messages and perhaps squash small commits together, starting at the point where feature-x branched off from develop:

git checkout feature-x
git log develop..feature-x --oneline  # note last commit hash, e.g., abc1234
git rebase -i abc1234~1
# (edit commits ...)

Useful branch commands

View your branch references in detail, including remote branches and tracking information:

git branch -avv

Remove references to all remote feature branches which have been deleted:

git remote prune origin

Remove a local obsolete feature-x branch:

git checkout develop
git branch -d feature-x   # or -D to force despite unmerged changes

Display current branch in shell prompt

When dealing with many different branches, it proves useful to add a current branch reminder within the shell prompt. To display the name of the current branch in the bash prompt, replace the PS1 variable definition in your ~/.bashrc shell resource file with the following:

PS1='\
$(  gitbranch=$(git rev-parse --abbrev-ref HEAD 2>&1);
    gitbranch=${gitbranch/%\ */};
    if [[ "$gitbranch" == "fatal:" ]]; then
        echo "[\u@\H \w]$ ";
    else
        echo "[\u@\H:\w \[\033[1;34m\]@ $gitbranch\[\033[0m\]]$ ";
    fi
)'

Note: this is not efficient, because the inlined script is run every time the prompt is displayed; but if you don't notice any lag, then no harm done.