Pol3He Analyzer Git HowTo
Contents
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.
- Go to this link: https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay
- 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
- Go to this link: https://eicweb.phy.anl.gov/jlab/hallc/exp/polhe3/hallc_replay
- Ensure you are logged in!
- 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.
- 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.
- 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'.
- Move into your existing working directory (on ifarm, for example).
- 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
- 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.
- 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.
- 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.
- 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 ...
- 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.
- 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 checkout -b test-upstream-merge
git merge upstream/master
- 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.