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 copy of your repo that you can work in

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.

In general, you should be working on the JLab Farm with code in our group directory.

1. Follow the Exercise 1 of the PolHe3 Analysis Tutorial.

However, make a clone of your personal repo instead of the 'upstream' repo.

1. • Do this by replacing git clone https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay.git with a link to your repo 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
2. Make an 'upstream' nickname in your working repo that you can use to reference the repo
   • • git remote add upstream https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay.git

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.