ROOT Analyzer/Git

Hall C uses the Git version control system to manage development of the Hall C 12 Gev analysis software. The Hall C analyzer uses the framework of the Hall A PODD analyzer.

Some general information on how to work with git can be found on the Git Howto page, and at #Git References.

The git repository of hcana on the web at github.com.

Setting up Git

You should have git, with at least version 1.5.3 installed on your computer. Most linux systems will have git installed.

• NOTE: git 1.7.x (or newer) is much, much better. We should have this rolled out on most machines at JLab and it is typically the default on personal installations. If you find an older version on a JLab-controlled machine you are advised to request an upgrade by submitting a JLab CCPR.

Personalize git on your machine with

 git config --global user.name "Firstname Lastname"
 git config --global user.email "your_email@youremail.com"

By default, git pops up the vi editor for the user write comments when making commits. If you prefer emacs, do

 git config --global core.editor "emacs"

Retrieving the Hall C analyzer with git

The following instructions are for users who plan to contribute to developing the analyzer, either for general use, or for a specific experiment. Establish an account on github.com is required. See the section "Read-only access" below for how to retrieve the code without needing an account.

Setup and creating a personal fork of the analyzer

1. If you don't already have one, create a personal account on github.com.
2. Follow the directions on the github.com for storing your public ssh key on the site. (NOTE: The github instructions ask you to install a program called "xclip" to help upload your public key. This is unnecessary - you can just "click and paste".)
3. Go to https://github.com/JeffersonLab/hcana.
4. Optionally select Watch to be notified of changes to hcana.
5. Click the Fork button to create your own copy of the hcana repository on github.
6. On the computer that you plan to run and develop the analyzer, type:
   git clone git@github.com:GitHub-Username/hcana.git
   where GitHub-Username is the name of the account that you created.
7. Do
   cd hcana
8. Execute the command
   git remote add --track develop upstream git@github.com:/JeffersonLab/hcana
   This will be needed to keep your forked copy and local machine copy of the code up to date with the main development repository.
9. For hcana, it is important to branch off the "develop" branch and NOT the "master" branch. So immediately do
   git checkout develop
10. To help keep a clean history and make it easier to update the main Jefferson Lab repository, please create your private branch from the "develop" branch with the command:
    git checkout -b featurebranchname
11. More info for working with git is in the Editing section

PODD submodule

hcana is written as an extension to Hall A analyzer, often known as podd. The source code to the Hall A analyzer is required to build the Hall C analyzer. The Hall A code is not automatically downloaded with the "git clone" command. Before proceeding, from your working directory do

 git submodule init
 git submodule update

If your version of git is too old, this last command may give an error. In that case, edit the file ".git/config", find [submodule "podd"] section and edit it to look like:

 [submodule "podd"]
          url = git://github.com/JeffersonLab/analyzer.git

Keeping personal fork up to date

The forked copy of hcana and the local copy on your machine made do not automatically stay up to date with changes made to the main development repository. The following commands will update your local copy and the forked copy on GitHub. This update procedure should be done before using analyzer and before starting to edit some changes or additions to the code. From your hcana directory, do:

 git checkout develop
 git fetch upstream
 git merge upstream/develop
 git push origin develop

If the version of the podd (hall A analyzer) being used by hcana has changed, it is also necessary to update the submodule. Type git status, and if it shows that podd is modified, do:

 git submodule sync
 git submodule update

Editing code and contributing back

It is important that any code development be made public early and often. We will follow the pattern here for developing code.

1. Follow the above procedure to update your repository with the current state of the develop branch in the main repository.
2. Go to the develop branch with
   git checkout develop
   Do not edit any files while in the develop branch. This is so that your develop branch stays a clean copy of the main repository.
3. Optional: Visit the http://github.com/JeffersonLab/hcana/ and create an "Issue" that describes the work that you are going to do.
4. Create a new branch, with a descriptive branch name with
   git checkout -b featurebranchname
5. Do some work.
6. Everytime that makes sense (e.g. once a day, or everytime a logical set of changes have been made.) commit your changes with
   git commit -a
   or
   git commit filename1 filename2 ...
   
7. Push your changes to a branch on your GitHub respository.
   git push origin featurebranchname
   This can be done often as it does not change the main repository.
8. When ready to request that your changes be merged in with the main repository, go to your GitHub page, select the branch featurebranchname and select pull request.
9. Wait for your "pull request" to be commented upon by other collaborators or accepted by a maintainer. When the pull request has been accepted to your satisfaction, it is safe to delete featurebranchname both on your local machine and on your GitHub account.
10. Before starting new work, make sure you update your local and GitHub repositories as described above.

Useful commands for cleaning up git commit history

1. After having finished making the commits in the featurebranchname which you would like to combine into one commit when merging in the develop branch. checkout develop branch and do git merge --squash featurebranchname and git commit -v to add new comment
2. Use the rebase command. See rebase manual page for examples.
3. Some hints from Ole Hansen
   1. Before fetching anything from upstream, use git rebase to collapse your local feature branch's history into a single (or very few) commits. Your branchpoint is probably still called "develop" unless you fetched in the meantime.
   2. Fetch upstream and merge upstream/develop into your local develop branch (should fast forward)
   3. Switch back to your feature branch and rebase onto the updated develop. Unless you worked on files that were also updated upstream, this will usually also fast forward and should at least not give any conflicts.
   4. Push the rebased feature branch to your github repo and make a pull request

Read only access

If you want to download the code to read it or use it, but do not plan to contribute changes back, retrieve the analyzer with:

 git clone git://github.com/JeffersonLab/hcana.git

In some places the "git" protocol may be blocked by a firewall. In that case use:

 git clone https://github.com/JeffersonLab/hcana.git

Using the analyzer

See Analyzer/Compiling and Analyzer/Running to try out the code.

Git References

Hall C wiki Git_Howto page

We will try to follow the branching model described in: A successful Git branching model