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 "email@example.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
- If you don't already have one, create a personal account on github.com.
- 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".)
- Go to https://github.com/JeffersonLab/hcana.
- Optionally select Watch to be notified of changes to hcana.
- Click the Fork buton to create your own copy of the hcana repository on github.
- On the computer that you plan to run and develop the analyzer, type:
git clone firstname.lastname@example.org:GitHub-Username/hcana.git
where GitHub-Username is the name of the account that you created.
- Execute the command
git remote add --track develop upstream email@example.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.
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
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.
- Follow the above procedure to update your repository with the current state of the develop branch in the main repository.
- Go to the develop branch with
git checkout develop</br> 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.
- Optional: Visit the http://github.com/JeffersonLab/hcana/ and create an "Issue" that describes the work that you are going to do.
- Create a new branch, with a descriptive branch name with
git checkout -b featurebranchname
- Do some work.
- 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
git commit filename1 filename2 ...
- 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.
- 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.
- 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.
- Before starting new work, make sure you update your local and GitHub repositories as described above.
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:
Using the analyzer
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.
We will try to follow the branching model described in: A successful Git branching model