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

NOTE: Do NOT use the "--global" argument to git unless you are logged in under your personal username.
      If you omit "--global", then the setting will only apply to the git repo that you are currently working on.

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"

Firewall issues at JLab

NOTE: As of November 2018 the http_proxy/https_proxy variables should not be needed (and should be removed from existing configurations)
 The 'jprox.jlab.org' machine will be disabled at some point and it will look like your network connection has failed.

If you try to interact with github and the command stalls for a long time before failing, you are probably running into a firewall problem and need to tell git to use a proxy. Run these two commands: If you set the above variables inside git following the old instructions, you can remove them by running this:

 git config --global --unset http_proxy
 git config --global --unset https_proxy

You should also remove/comment-out any shell environment variables like this https_proxy = https://jprox.jlab.org:8081 in your shell's rc-file.

In order to avoid problems with JLab firewalls, run this command so git will automagically substitute the https protocol instead of the git protocol:

 git config --global url."https://github".insteadOf git://github

If you wish to use ssh-key authentication with github then ssh protocol is a better choice. Use this line instead of the above command:

 git config --global url."ssh://git@github.com".insteadOf git://github.com

Non-fatal errors/warnings running git on ifarm

You may see these warnings when you run git on the ifarm machines. They are non-fatal and can be ignored. (They are due to a mismatch between RHEL6 and CentOS6 libraries...)

 ... /lib64/libz.so.1: no version information available (required by git)
 ... /usr/lib64/libcrypto.so.10: no version information available (required by git)

List your global git configuration

Not sure what is set in your global configuration? Run this command:

 git config --list --global

See git config --help for more details.

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.

Setup and creating a personal fork of the analyzer

If you want to download the code to read it or use it, but do not plan to contribute changes back, you can retrieve the analyzer with git clone https://github.com/JeffersonLab/hcana.git and proceed to the next step.

Otherwise, follow the instructions below:

1. If you don't already have one, create a personal account on github.com.
2. Setup ssh on
   1. Generate ssh key if you do not have one.
      1. ssh-keygen -t dsa ( when prompted for pass phrase just hit return )
      2. ssh-add ~/.ssh/id_dsa
   2. Put ssh public key on Github
      1. Open the "Settings" in the pull down menu on the extreme right.
      2. Go to "SSH keys"
      3. Click on "new ssh key" button. At terminal type "more ~/.ssh/id_dsa.pub". Copy the code and paste into github.
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 either:
   1. 
      git clone git@github.com:GitHub-Username/hcana.git
      where GitHub-Username is the name of the account that you created.
   2. 
      git clone https://github.com/GitHub-Username/hcana.git
      where GitHub-Username is the name of the account that you created.
   3. On cdaq machines you must use https.
7. Do
   cd hcana
8. Do
   git remote -v and it should return (https://github.com/ could be git@github.com:)
   origin https://github.com/Github-UserName/hcana.git (fetch)
   origin https://github.com/Github-UserName/hcana.git (pull)
9. Execute the command
   git remote add --track develop upstream https://github.com/JeffersonLab/hcana
   or
   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.
10. For hcana, it is important to branch off the "develop" branch and NOT the "master" branch. So immediately do
    git checkout develop
11. 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
12. 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 = https://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.
11. If the develop branch on the main repository ( your "upstream" repository) changes and you want to incorporate the changes into the branch featurebranchname that you are working on then follow these steps:

  git checkout develop
  git fetch upstream
  git merge upstream/develop
  git push origin develop
  git checkout featurebranchname
  git rebase -i develop

If there is a conflict with the rebasing then git will let you know.

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

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