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 Hall C code is hosted on github.com. To retrieve the code, follow below:

Read/write 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 https://github.com/JeffersonLab/hcana.git

Read/write access

If you plan to contribute changes back to hcana, which is highly encouraged, do the following to get set up:

• Create an account on github.com and follow the directions 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".)
• Once you have signed into github then go to https://github.com/JeffersonLab/hcana.
• Optionally select Watch to be notified of chagnes to hcana.
• Click the Fork button to create your own copy of he hcana repo on github.
• On the computer that you want to run or develop hcana, type:

 git clone git@github.com:GitHub-Username/hcana.git

where GitHub-Username is your username.

• Now the remote "origin" points to your personal copy of the hcana repository on github. After cloning, you will be in the "develop" branch, which is the current default branch. (Formal releases will be on the master branch.)
• You can keep your local copy up to date with the main repository:
  • One time, do

 git remote add upstream https://github.com/JeffersonLab/hcana

• • To fetch the latest updates, do

 git fetch upstream

• • To merge the main development branch with your working code, do

 git merge upstream/develop

PODD submodule

The hcana project includes a git "submodule" containing the source code for the Hall A 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, (as it is on many jlab machines including ifarm*), 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 = https://github.com/JeffersonLab/analyzer.git

Using the analyzer

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

Using Git to develop the analyzer

We need to have a workflow methodology for developing the Hall C analyzer. "Understanding the Git Workflow" and "Our Simple Git Workflow" have some discussion of straight forward workflows.

Basically if you want to develop the analyzer, clone the git archive as described above. Then create a private branch for yourself with

 git checkout -b myprivatebranch

Then work on the code do git commit -a frequently. Don't worry about committing changes frequently. You will have the opportunity to clean up the revision history before pushing your changes to the public repository.

There are a variety of ways to share your work. If someone you want to share it with is on the same machine (and your files are readable), he can clone or pull from your archive. If your working directory is available on the web, then anyone can clone or pull from it. To put your changes in the public git repository, contact one of the code maintainers.

Branches

The git repository may contain several branches in addition to the default "develop" branch. These branches may be for different experiments, or for work in progress that a developer wants to share. To see what branches exist, type

 git pull origin    #Updates the local repo from the public repo
 git branch -a

from the directory you cloned the project into. For example, at the moment, there is a branch "simon-shower" which contains code being developed for the shower counters. This branch will be listed as "remotes/origin/simon-shower". To check this branch out, type

 git checkout simon-shower

The master branch is reserved for major releases.

Publishing Changes

It is important that any code development be made public early and often. There are two ways of sharing your changes.

Push directly to a branch on a repository

If you have previously retrieved the analyzer from github, you need to change to the hallc git server to be able to push code. To setup the ability publish your work to the public repository, you must modify the remote named "origin". You can do this by running the command

       git remote -v  # just to list what the remotes look like beforehand
       git remote set-url --push origin git@hallcgit.jlab.org:hcana.git 
       git remote -v  # just to see what the remotes look like after modification

or you edit the file "hcana/.git/config". Find the sectioon [remote "origin"]. Then replace "url" line after it with

       url = git@hallcgit.jlab.org:hcana.git

Gitweb will have to be told to allow access from your account. To do this, contact Steve Wood.

To publish changes, make sure you are doing your work in a branch other than develop. When you are ready to post it, do

git push origin branchname

Then let Steve Wood know and he will merge your code into the develop branch.

Send a pull request to the maintainer (safe method)

This method is a bit more safe and you don't need any special permission.

First you have to be hosting a public repository. You can set up your own (which can be difficult) or you can use one of many (free) online services like github. Once you have an account you can create a fork by going here and clicking on fork in the upper right. This creates a copy of the repository of your own.

To add the remote you can do the following

      git remote add github git@github.com/USERNAME/hcana.git

Now you can push your changes to your repository (and browse on the web).

      git push github SOME_BRANCH

Then you send a "pull request" to the maintainer. This can be done with a simple email pointing them to the public repo and branch or using github.com's online pull request feature.

Either way, the maintainer inspects your changes before merging.

Git References

Brad's Hall C wiki Git_Howto page

Brad's "Git Cheat-sheet": 7 steps to developing with git.

Graphical cheatsheet: 1 page reference

Git Magic: An online book about using Git.

The Git Community Book: The official book introducing Git.

Understanding the Git Workflow

Our Simple Git Workflow

Git flow used by GitHub

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