Pol3He Analyzer Git HowTo

Create your account on the ANL GitLab server

We will be hosting our main repositories on the ANL GitLab server. This works a lot like GitHub.

1. Go to this link: https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay
2. Sign-in/Register using the button on the upper-right.

Create a 'Fork' of our main hallc_replay repository

You will only do this once. This will become your primary remote repository and backup for your personal work.

Its nickname in your local repo should be origin

1. Go to this link: https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay
   • Ensure you are logged in!
2. Click on the 'Fork' button on the upper-right and a copy of the main repo will be created under your GitLab account.

Pull down a working copy of your repo

You can do this on multiple machines if you like. Just remember to git push work up to your remote repo so you can stay backed-up and synchronized in your other working repositories. This is where you actually do your work.

In general, you should be working on the JLab Farm with your repo in the /group/c-polhe3/Users/<your_username>/... directory.

1. Follow Exercise 1 of the PolHe3 Analysis Tutorial to do this.
   • However, make a clone of your personal repo instead of the 'upstream' repo.
   • Modify the git clone https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay.git step to use a link to your repo.
   • For example: git clone https://eicweb.phy.anl.gov/jlab/hallc/exp/XXXX/hallc_replay.git
     • XXXX will be some part of your ANL GitLab username.
     • You can find your personal URL by going to your forked repo URL and clicking on the 'Clone' button.
     • If you follow these instructions, then your personal GitLab repo will have the nickname origin. That is what you want.
2. Make an 'upstream' nickname in your working repo that you can use to reference our main repo.
   • git remote add upstream https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay.git

If you want to update an existing local repo

If you already have a working repository, you should update the nicknames so that 'origin' points to your personal repo and 'upstream' points at the main repo.

For example, if you are working in a repo you created from the Tutorial session noted above, then your 'origin' is the main repo. You want to do two things: switch 'origin' to point at your personal upstream fork, and change the nickname for the main repo to 'upstream'.

1. Move into your existing working directory (on ifarm, for example).
2. Change the nickname for the https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay.git repo to 'upstream'

   git remote rename origin upstream

3. Connect your working directory to your personal fork

   git remote add origin https://eicweb.phy.anl.gov/jlab/hallc/exp/XXXX/hallc_replay.git

   • XXXX will be some part of your ANL GitLab username.
   • You can find your personal URL by going to your forked repo URL and clicking on the 'Clone' button.
4. Reset your local master branch track your personal repo (now nicknamed 'origin')

   git branch --set-upstream-to origin/master

General Software Development Outline

NOTE: There are many ways to work with git. Watch the videos and/or read the GIT How-tos. In general, it is good form to use git checkout -b my-new-feature and develop outside of your local 'master' branch. The idea there is to make sure that 'master' is always in a 'known good' working state.

However, the instructions below assume you are doing your local development in 'master'. That is OK if you're getting started with all this.

1. Hack on your code in your local repo

   git add -p

   git commit -v

   NOTE: Do you best to document your changes in the git commit. This can help a lot later on.

2. Periodically push your changes to your personal repo at ANL. This is important! It is a backup, and helps document your progress for others.

   git push ...

3. Pull down and merge changes from 'upstream' periodically. Don't forget to do this! You want to stay current with the main repo.

   git fetch --all

   Merge changes from 'upstream' into your local working repository. I'm assuming that is 'master' below.

   git checkout master

   The next bit takes an extra step that will help avoid potentially messing up your working 'master' by merging into a test branch first. That is optional. You can merge 'upstream/master' directly into your local 'master' by just running git pull and skipping the rest.

   git checkout -b test-upstream-merge

   git merge upstream/master

4. Check and if it looks good, merge that test branch it into your local working 'master' branch

   git checkout master

   git merge test-merge-whatever

   git branch --delete test-upstream-merge

More information

• Farm Use and Computing Resources Tips and Tricks (Updated 2019) -- Brad Sawatzky
• List of Pol He3 Analysis Resources
• A list of GIT How-tos that you should review.