Getting Started - Git

Version Control

We use git for version control and GitHub as our git server. Here is the Git Reference Manual. Familiarize yourselves with basic git usage. The best ways to learn Git is to get hands-on experience! Make your own separate repos. Push to Git, maybe even pair up and work collaboratively with your peers on test projects. A set of common commands is listed below. It can be used for code development or other things like versioning your dissertation!

Source of concise information

• Visualization of commands
• git cheat sheet
• Pro Git Book!

Commonly Used Git Commands

git clone	git push	git merge
git fetch	git pull	git log
git checkout	git rebase	git remote

Analysis Flow Chart and Version Control

• Analysis is broken up into several passes.
  • Each pass makes incremental improvements on detector calibrations, offsets, and replay branches.
  • When the group has decided a pass has come to conclusion, the pass will be closed and a mass replay will be ran over all of the data.
  • Each pass is self contained within a git branch on the main repository Jefferson Lab hallc_replay_XEM
• Details of a pass
  • Each XEM2 user that is making contributions will make a Fork of JeffersonLab/hallc_replay_XEM.
  • When a group member is assigned a task to complete, they will check out a new featurebranch based on the current pass.
  • Contributions made by a group member will be pushed up to their origin. This is the Fork of JeffersonLab/hallc_replay_XEM.
    • A pull request is submitted directly from the featurebranch the member has completed work on to the JeffersonLab/hallc_replay_XEM pass we are all on.
    • Refer to the Fork/Pull Request recipe below.
  • Keep your local pass up-to-date. Deviations will cause issues contributing your work to the pass branch via a pull requests.
    • Each time you submit a pull request you should make sure you rebase your repo off of the updated pass branch.

      The section Staying up-to-date and Rebasing describes how to update your local pass branch and rebase your featurebranch.

Setting SSH for GitHub at JLab

1. Generate ssh key if you do not have one.
   1. ssh-keygen (when prompted for file in which to save the key and pass phrase, just hit return )
2. Put ssh public key on Github
   1. Open "Settings" from the pull down menu in the top right.
   2. Go to "SSH and GPG keys"
   3. Click on "new ssh key" button. At terminal type "more ~/.ssh/id_rsa.pub". Copy the code and paste into github.
   • Note: The ssh key may not work right away. If this happens, just log off from the iFarm machine and wait a few minutes for the key to start working. You may be unable to login to the iFarm for a few minutes, this is OK. Once you are able to login to the iFarm again the ssh key should be working, so you should be able to start cloning remote repositories.

Setup and creating a personal fork of hallc_replay_XEM

1. If you don't already have one, create a personal account on github.com.
2. Setup ssh for git
   • Follow the instructions in the Setting SSH for GitHub at JLab section
3. Go to https://github.com/JeffersonLab/hallc_replay_XEM.
4. Optionally select Watch to be notified of changes to hallc_replay_XEM.
5. Click the Fork button to create your own copy of the hallc_replay_XEM repository on GitHub.
   1. When prompted, de-select "Copy the main branch only", we want all the branches!
6. On the computer that you plan to run and develop hallc_replay_XEM, type either:
   1. 
      git clone git@github.com:GitHub-Username/hallc_replay_XEM.git
      where GitHub-Username is the name of the account that you created.
   2. 
      git clone https://github.com/GitHub-Username/hallc_replay_XEM.git
      where GitHub-Username is the name of the account that you created.
7. Do
   cd hallc_replay_XEM
   1. At this point you can setup the replay to run scripts. This is done by following the Setting Up the Replay Section of Starting Out
8. Do
   git remote -v and it should return (https://github.com/ could be git@github.com:)
   origin https://github.com/Github-UserName/hallc_replay_XEM.git (fetch)
   origin https://github.com/Github-UserName/hallc_replay_XEM.git (pull)
9. Execute the command
   git remote add --track pass# upstream https://github.com/JeffersonLab/hallc_replay_XEM
   or
   git remote add --track pass# upstream git@github.com:JeffersonLab/hallc_replay_XEM
   This will be needed to keep your forked copy and local machine copy of the code up to date with the main pass repository.
10. For hallc_replay_XEM, it is important to branch off the "pass#" branch and NOT the "master" branch. So immediately do
    git checkout pass#
11. To help keep a clean history and make it easier to update the main Jefferson Lab repository, please create your private branch from the "pass#" branch with the command:
    git checkout -b featurebranchname
12. More info for working with git is in the Editing code and contributing back

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.

1. Follow the above procedure to update your repository with the current state of the pass# branch in the main repository.
2. Go to the pass# branch with
   git checkout pass#
   Do not edit any files while in the pass# branch. This is so that your pass# branch stays a clean copy of the main repository.
3. Optional: Visit the http://github.com/JeffersonLab/hallc_replay_XEM/ and create an "Issue" that describes the work that you are going to do.
4. Create a new branch, with a descriptive branch name with
   git checkout -b featurebranchname
5. Do some work.
6. 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
   or
   git commit filename1 filename2 ...
   
7. 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.
8. 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.
9. 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.
10. Before starting new work, make sure you update your local and GitHub repositories as described above.
11. If the pass# branch on the main repository ( your "upstream" repository) changes and you want to incorporate the changes into the branch featurebranchname that you are working on then follow these steps:

  git checkout pass#
  git fetch upstream
  git merge upstream/pass#
  git push origin pass#
  git checkout featurebranchname
  git rebase -i pass#

If there is a conflict with the rebasing then git will let you know.

Hierarchy

• Git is used as version control for all shared code
• We follow the Fork / Pull Request Paradigm. In the example, replace all master with pass#.
• This is the same workflow use for hcana contributions
• The replay repo is no longer a fork of hallc_replay. We need to watch that repo closely for changes.
• Dave is in charge of accepting pull requests into the JeffersonLab/hallc_replay_XEM repo.
• All XEM group members will 'Fork' Jefferson Lab's hallc_replay_XEM repository. The fork will appear on your GitHub account, that is your 'origin'.
  • JeffersonLab/hallc_replay_XEM is your 'upstream' repo. This area is common to all XEM2 users.
  • Changes can be made on a 'local' repo and then pushed to your 'origin'. All changes should fall under a specific pass#. Make sure you rebase your 'local' and 'origin' often to have the most up-to-date repo.
  • Once you have pushed your changes to your 'origin' under a new_feature_branch based on pass# branch, you can make a pull request to JeffersonLab/hallc_replay_XEM to add your changes into our 'upstream' pass# branch.
• Communications about new features / calibrations / etc will be sent via the hallc_replay_XEM Slack channel. Please watch the main repo (JeffersonLab/hallc_replay_XEM). This will notify you when collaborator have accepted pull requests and you should merge the changes into your pass# branch.

Remember: The point of this scheme is for us to Collaborate! We can independently work on different calibrations / scripts / etc and bring all of our changes together to spread out the workload.

Hierarchy Visualization

Used before, complicated

Lets say Casey added a branch to hallc_replay_XEM that you'd like to use. We want to put that on our origin, but the fetch upstream button on github does not add the new branch to your origin. To do this we must: First ensure you are tracking the remote upstream: git remote -v Lists all names of remote repositories and the path to them git remote add upstream git@github.com/mrcmor100/hallc_replay_XEM.git Now that we told our local where upstream is, we can track the new branch in our local: git checkout upstream_branch_name You could alternatively name this whatever you'd like (don't) git pull upstream upstream_branch_name Pulls from upstream to local git push origin local_branch_name local_branch_name should match upstream_branch_name! Great, now you have the upstream branch on your origin. Thing to check If Casey updates upstream_branch_name, will there be a fetch upstream option for that branch? Lets say we want to stop tracking old branches that no longer exist: git remote prune origin That'll do it for ya'!

Reset Repo (go back a commit)

http://www.inanzzz.com/index.php/post/zaqd/revert-last-commit-but-keep-all-the-changes-to-the-files-with-git-reset-soft-head

Working With Git Submodules

I found this to be a very good resource that covers git submodules with simple examples.

https://git-scm.com/book/en/v2/Git-Tools-Submodules