Pol3He Analyzer Git HowTo

From HallCWiki
Revision as of 17:54, 12 November 2020 by Brads (Talk | contribs) (Pull down a copy of your repo that you can work in)

Jump to: navigation, search


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.
  2. Make an 'upstream' nickname in your working repo that you can use to reference our main repo.

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. Make your 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