Difference between revisions of "ROOT Analyzer/Git"
(Updates for new hallc git server) |
(→Retrieving the Hall C analyzer with git) |
||
(55 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
[[category:12GeV Software]] | [[category:12GeV Software]] | ||
− | + | Hall C uses the [http://git-scm.com/ Git version control system] to manage development of the Hall C 12 Gev analysis software. The Hall C analyzer uses the framework of the Hall A [http://hallaweb.jlab.org/podd/html/ PODD] analyzer. | |
− | Some general information on how to work with git can be found on the [[Git Howto]] page. | + | Some general information on how to work with git can be found on the [[Git Howto]] page, and at [[#Git References]]. |
+ | |||
+ | The [https://github.com/JeffersonLab/hcana git repository] of hcana on the web at github.com. | ||
== Setting up Git == | == Setting up Git == | ||
+ | |||
+ | NOTE: Do <b>NOT</b> use the "--global" argument to git unless you are logged in under <i>your</i> personal username. | ||
+ | If you omit "--global", then the setting will only apply to the git repo that you are currently working on. | ||
You should have git, with at least version 1.5.3 installed on your computer. Most linux systems will have git installed. | You should have git, with at least version 1.5.3 installed on your computer. Most linux systems will have git installed. | ||
+ | * NOTE: git 1.7.x (or newer) is much, much better. We should have this rolled out on most machines at JLab and it is typically the default on personal installations. If you find an older version on a JLab-controlled machine you are advised to request an upgrade by submitting a [https://mis.jlab.org/mis/ccpr/ccpr_user/ JLab CCPR]. | ||
+ | |||
Personalize git on your machine with | Personalize git on your machine with | ||
Line 12: | Line 19: | ||
git config --global user.email "<i>your_email@youremail.com</i>" | git config --global user.email "<i>your_email@youremail.com</i>" | ||
− | By default, git pops up the vi editor | + | By default, git pops up the vi editor for the user write comments when making commits. |
+ | <span title="But don't do this, stick with vim.">If you prefer emacs, do</span> | ||
+ | <span title="Really, don't do this. Once you start down the dark path...">git config --global core.editor "emacs"</span> | ||
− | + | === Firewall issues at JLab === | |
− | + | '''NOTE: As of November 2018 the http_proxy/https_proxy variables should ''not'' be needed (and should be removed from existing configurations)''' | |
− | + | The 'jprox.jlab.org' machine will be disabled at some point and it will look like your network connection has failed. | |
− | git config --global | + | If you try to interact with github and the command stalls for a long time before failing, you are probably running into a firewall problem and need to tell git to use a proxy. Run these two commands: |
+ | If you set the above variables inside git following the old instructions, you can remove them by running this: | ||
+ | git config --global --unset http_proxy | ||
+ | git config --global --unset https_proxy | ||
− | + | You should also remove/comment-out any shell environment variables like this <code>https_proxy = https://jprox.jlab.org:8081</code> in your shell's rc-file. | |
− | |||
− | |||
− | + | In order to avoid problems with JLab firewalls, run this command so git will automagically substitute the https protocol instead of the git protocol: | |
+ | git config --global url."https://github".insteadOf git://github | ||
− | + | If you wish to use ssh-key authentication with github then ssh protocol is a better choice. Use this line '''instead''' of the above command: | |
+ | git config --global url."ssh://git@github.com".insteadOf git://github.com | ||
− | === | + | === Non-fatal errors/warnings running git on ifarm === |
+ | You may see these warnings when you run git on the ifarm machines. They are non-fatal and can be ignored. (They are due to a mismatch between RHEL6 and CentOS6 libraries...) | ||
+ | ... /lib64/libz.so.1: no version information available (required by git) | ||
+ | ... /usr/lib64/libcrypto.so.10: no version information available (required by git) | ||
− | + | === List your global git configuration === | |
+ | Not sure what is set in your global configuration? Run this command: | ||
+ | git config --list --global | ||
− | + | See <code>git config --help</code> for more details. | |
− | + | == Retrieving the Hall C analyzer with git == | |
− | + | The following instructions are for users who plan to contribute to developing the analyzer, either for general use, or for a specific experiment. Establish an account on github.com is required. | |
− | |||
− | + | === Setup and creating a personal fork of the analyzer === | |
+ | If you want to download the code to read it or use it, but do not plan to contribute changes back, you can retrieve the analyzer with | ||
+ | <code>git clone https://github.com/JeffersonLab/hcana.git</code> and proceed to the next step. | ||
− | + | Otherwise, follow the instructions below: | |
+ | #If you don't already have one, create a personal account on [https://github.com github.com]. | ||
+ | #Setup ssh on | ||
+ | ##Generate ssh key if you do not have one. | ||
+ | ###ssh-keygen -t dsa ( when prompted for pass phrase just hit return ) | ||
+ | ###ssh-add ~/.ssh/id_dsa | ||
+ | ##Put ssh public key on Github | ||
+ | ### Open the "Settings" in the pull down menu on the extreme right. | ||
+ | ### Go to "SSH keys" | ||
+ | ### Click on "new ssh key" button. At terminal type "more ~/.ssh/id_dsa.pub". Copy the code and paste into github. | ||
+ | #Go to [https://github.com/JeffersonLab/hcana https://github.com/JeffersonLab/hcana]. | ||
+ | #Optionally select '''Watch''' to be notified of changes to hcana. | ||
+ | #Click the '''Fork''' button to create your own copy of the hcana repository on github. | ||
+ | #On the computer that you plan to run and develop the analyzer, type either: | ||
+ | ##<br><code>git clone git@github.com:''GitHub-Username''/hcana.git</code><br> where ''GitHub-Username'' is the name of the account that you created. | ||
+ | ##<br><code>git clone https://github.com/''GitHub-Username''/hcana.git</code><br> where ''GitHub-Username'' is the name of the account that you created. | ||
+ | ## On cdaq machines you must use https. | ||
+ | #Do <br><code>cd hcana</code> | ||
+ | #Do <br><code>git remote -v</code> and it should return (''https://github.com/ could be git@github.com:'')<br>origin https://github.com/''Github-UserName''/hcana.git (fetch)<br>origin https://github.com/''Github-UserName''/hcana.git (pull) | ||
+ | #Execute the command<br><code>git remote add --track develop upstream https://github.com/JeffersonLab/hcana</code><br> or <br><code>git remote add --track develop upstream git@github.com:JeffersonLab/hcana</code><br> This will be needed to keep your forked copy and local machine copy of the code up to date with the main development repository. | ||
+ | #For hcana, it is important to branch off the "develop" branch and NOT the "master" branch. So immediately do <br><code>git checkout develop</code> | ||
+ | #To help keep a clean history and make it easier to update the main Jefferson Lab repository, please create your private branch from the "develop" branch with the command: <br><code>git checkout -b featurebranchname</code> | ||
+ | # More info for working with git is in the [https://hallcweb.jlab.org/wiki/index.php/Analyzer/Git#Editing_code_and_contributing_back Editing section] | ||
− | + | === PODD submodule === | |
+ | hcana is written as an extension to [http://hallaweb.jlab.org/podd/ Hall A analyzer], often known as podd. The source code to the Hall A analyzer is required to build the Hall C analyzer. The Hall A code is not automatically downloaded with the "git clone" command. Before proceeding, from your working directory do | ||
− | |||
git submodule init | git submodule init | ||
git submodule update | git submodule update | ||
− | + | If your version of git is too old, this last command may give an error. In that case, edit the file ".git/config", find [submodule "podd"] section and edit it to look like: | |
− | + | [submodule "podd"] | |
− | + | url = https://github.com/JeffersonLab/analyzer.git | |
− | + | ||
− | + | === Keeping personal fork up to date === | |
− | + | The forked copy of hcana and the local copy on your machine made do not automatically stay up to date with changes made to the main development repository. The following commands will update your local copy and the forked copy on GitHub. This update procedure should be done before using analyzer and before starting to edit some changes or additions to the code. From your hcana directory, do: | |
− | + | ||
− | + | ||
git checkout develop | git checkout develop | ||
− | + | git fetch upstream | |
+ | git merge upstream/develop | ||
+ | git push origin develop | ||
+ | If the version of the podd (hall A analyzer) being used by hcana has changed, it is also necessary to update the submodule. Type <code>git status</code>, and if it shows that podd is modified, do: | ||
+ | git submodule sync | ||
+ | git submodule update | ||
− | + | === 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. | ||
+ | #Follow the above procedure to update your repository with the current state of the develop branch in the main repository. | ||
+ | #Go to the develop branch with<br><code>git checkout develop</code><br> Do not edit any files while in the develop branch. This is so that your develop branch stays a clean copy of the main repository. | ||
+ | #Optional: Visit the [http://github.com/JeffersonLab/hcana/ http://github.com/JeffersonLab/hcana/] and create an "Issue" that describes the work that you are going to do. | ||
+ | #Create a new branch, with a descriptive branch name with <br><code>git checkout -b ''featurebranchname''</code> | ||
+ | #Do some work. | ||
+ | #Everytime that makes sense (e.g. once a day, or everytime a logical set of changes have been made.) commit your changes with <br><code>git commit -a</code><br> or <br><code>git commit ''filename1'' ''filename2'' ...</code><br> | ||
+ | #Push your changes to a branch on your GitHub respository.<br><code>git push origin ''featurebranchname''</code><br> This can be done often as it does not change the main repository. | ||
+ | #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. | ||
+ | #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. | ||
+ | #Before starting new work, make sure you update your local and GitHub repositories as described above. | ||
+ | # If the develop 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 develop | ||
+ | git fetch upstream | ||
+ | git merge upstream/develop | ||
+ | git push origin develop | ||
+ | git checkout ''featurebranchname'' | ||
+ | git rebase -i develop | ||
+ | If there is a conflict with the rebasing then git will let you know. | ||
− | + | === Useful commands for cleaning up git commit history === | |
+ | #After having finished making the commits in the ''featurebranchname'' which you would like to combine into one commit when merging in the ''develop'' branch. checkout develop branch and do ''git merge --squash featurebranchname'' and ''git commit -v'' to add new comment | ||
+ | #Use the rebase command. See [http://schacon.github.io/git/git-rebase.html rebase manual page ] for examples. | ||
+ | #Some hints from Ole Hansen | ||
+ | ##Before fetching anything from upstream, use git rebase to collapse your local feature branch's history into a single (or very few) commits. Your branchpoint is probably still called "develop" unless you fetched in the meantime. | ||
+ | ##Fetch upstream and merge upstream/develop into your local develop branch (should fast forward) | ||
+ | ##Switch back to your feature branch and rebase onto the updated develop. Unless you worked on files that were also updated upstream, this will usually also fast forward and should at least not give any conflicts. | ||
+ | ##Push the rebased feature branch to your github repo and make a pull request | ||
+ | |||
+ | == Using the analyzer == | ||
See [[Analyzer/Compiling]] and [[Analyzer/Running]] to try out the code. | See [[Analyzer/Compiling]] and [[Analyzer/Running]] to try out the code. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== Git References == | == Git References == | ||
− | + | Hall C wiki [[Git_Howto ]] page | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
We will try to follow the branching model described in: [http://nvie.com/posts/a-successful-git-branching-model/ A successful Git branching model] | We will try to follow the branching model described in: [http://nvie.com/posts/a-successful-git-branching-model/ A successful Git branching model] |
Latest revision as of 18:55, 30 June 2020
Hall C uses the Git version control system to manage development of the Hall C 12 Gev analysis software. The Hall C analyzer uses the framework of the Hall A PODD analyzer.
Some general information on how to work with git can be found on the Git Howto page, and at #Git References.
The git repository of hcana on the web at github.com.
Contents
Setting up Git
NOTE: Do NOT use the "--global" argument to git unless you are logged in under your personal username. If you omit "--global", then the setting will only apply to the git repo that you are currently working on.
You should have git, with at least version 1.5.3 installed on your computer. Most linux systems will have git installed.
- NOTE: git 1.7.x (or newer) is much, much better. We should have this rolled out on most machines at JLab and it is typically the default on personal installations. If you find an older version on a JLab-controlled machine you are advised to request an upgrade by submitting a JLab CCPR.
Personalize git on your machine with
git config --global user.name "Firstname Lastname" git config --global user.email "your_email@youremail.com"
By default, git pops up the vi editor for the user write comments when making commits. If you prefer emacs, do
git config --global core.editor "emacs"
Firewall issues at JLab
NOTE: As of November 2018 the http_proxy/https_proxy variables should not be needed (and should be removed from existing configurations) The 'jprox.jlab.org' machine will be disabled at some point and it will look like your network connection has failed.
If you try to interact with github and the command stalls for a long time before failing, you are probably running into a firewall problem and need to tell git to use a proxy. Run these two commands: If you set the above variables inside git following the old instructions, you can remove them by running this:
git config --global --unset http_proxy git config --global --unset https_proxy
You should also remove/comment-out any shell environment variables like this https_proxy = https://jprox.jlab.org:8081
in your shell's rc-file.
In order to avoid problems with JLab firewalls, run this command so git will automagically substitute the https protocol instead of the git protocol:
git config --global url."https://github".insteadOf git://github
If you wish to use ssh-key authentication with github then ssh protocol is a better choice. Use this line instead of the above command:
git config --global url."ssh://git@github.com".insteadOf git://github.com
Non-fatal errors/warnings running git on ifarm
You may see these warnings when you run git on the ifarm machines. They are non-fatal and can be ignored. (They are due to a mismatch between RHEL6 and CentOS6 libraries...)
... /lib64/libz.so.1: no version information available (required by git) ... /usr/lib64/libcrypto.so.10: no version information available (required by git)
List your global git configuration
Not sure what is set in your global configuration? Run this command:
git config --list --global
See git config --help
for more details.
Retrieving the Hall C analyzer with git
The following instructions are for users who plan to contribute to developing the analyzer, either for general use, or for a specific experiment. Establish an account on github.com is required.
Setup and creating a personal fork of the analyzer
If you want to download the code to read it or use it, but do not plan to contribute changes back, you can retrieve the analyzer with
git clone https://github.com/JeffersonLab/hcana.git
and proceed to the next step.
Otherwise, follow the instructions below:
- If you don't already have one, create a personal account on github.com.
- Setup ssh on
- Generate ssh key if you do not have one.
- ssh-keygen -t dsa ( when prompted for pass phrase just hit return )
- ssh-add ~/.ssh/id_dsa
- Put ssh public key on Github
- Open the "Settings" in the pull down menu on the extreme right.
- Go to "SSH keys"
- Click on "new ssh key" button. At terminal type "more ~/.ssh/id_dsa.pub". Copy the code and paste into github.
- Generate ssh key if you do not have one.
- Go to https://github.com/JeffersonLab/hcana.
- Optionally select Watch to be notified of changes to hcana.
- Click the Fork button to create your own copy of the hcana repository on github.
- On the computer that you plan to run and develop the analyzer, type either:
git clone git@github.com:GitHub-Username/hcana.git
where GitHub-Username is the name of the account that you created.git clone https://github.com/GitHub-Username/hcana.git
where GitHub-Username is the name of the account that you created.- On cdaq machines you must use https.
- Do
cd hcana
- Do
git remote -v
and it should return (https://github.com/ could be git@github.com:)
origin https://github.com/Github-UserName/hcana.git (fetch)
origin https://github.com/Github-UserName/hcana.git (pull) - Execute the command
git remote add --track develop upstream https://github.com/JeffersonLab/hcana
orgit remote add --track develop upstream git@github.com:JeffersonLab/hcana
This will be needed to keep your forked copy and local machine copy of the code up to date with the main development repository. - For hcana, it is important to branch off the "develop" branch and NOT the "master" branch. So immediately do
git checkout develop
- To help keep a clean history and make it easier to update the main Jefferson Lab repository, please create your private branch from the "develop" branch with the command:
git checkout -b featurebranchname
- More info for working with git is in the Editing section
PODD submodule
hcana is written as an extension to Hall A analyzer, often known as podd. The source code to the Hall A analyzer is required to build the Hall C analyzer. The Hall A code is not automatically downloaded with the "git clone" command. Before proceeding, from your working directory do
git submodule init git submodule update
If your version of git is too old, this last command may give an error. In that case, edit the file ".git/config", find [submodule "podd"] section and edit it to look like:
[submodule "podd"] url = https://github.com/JeffersonLab/analyzer.git
Keeping personal fork up to date
The forked copy of hcana and the local copy on your machine made do not automatically stay up to date with changes made to the main development repository. The following commands will update your local copy and the forked copy on GitHub. This update procedure should be done before using analyzer and before starting to edit some changes or additions to the code. From your hcana directory, do:
git checkout develop git fetch upstream git merge upstream/develop git push origin develop
If the version of the podd (hall A analyzer) being used by hcana has changed, it is also necessary to update the submodule. Type git status
, and if it shows that podd is modified, do:
git submodule sync git submodule update
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.
- Follow the above procedure to update your repository with the current state of the develop branch in the main repository.
- Go to the develop branch with
git checkout develop
Do not edit any files while in the develop branch. This is so that your develop branch stays a clean copy of the main repository. - Optional: Visit the http://github.com/JeffersonLab/hcana/ and create an "Issue" that describes the work that you are going to do.
- Create a new branch, with a descriptive branch name with
git checkout -b featurebranchname
- Do some work.
- 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
orgit commit filename1 filename2 ...
- 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. - 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.
- 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.
- Before starting new work, make sure you update your local and GitHub repositories as described above.
- If the develop 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 develop git fetch upstream git merge upstream/develop git push origin develop git checkout featurebranchname git rebase -i develop
If there is a conflict with the rebasing then git will let you know.
Useful commands for cleaning up git commit history
- After having finished making the commits in the featurebranchname which you would like to combine into one commit when merging in the develop branch. checkout develop branch and do git merge --squash featurebranchname and git commit -v to add new comment
- Use the rebase command. See rebase manual page for examples.
- Some hints from Ole Hansen
- Before fetching anything from upstream, use git rebase to collapse your local feature branch's history into a single (or very few) commits. Your branchpoint is probably still called "develop" unless you fetched in the meantime.
- Fetch upstream and merge upstream/develop into your local develop branch (should fast forward)
- Switch back to your feature branch and rebase onto the updated develop. Unless you worked on files that were also updated upstream, this will usually also fast forward and should at least not give any conflicts.
- Push the rebased feature branch to your github repo and make a pull request
Using the analyzer
See Analyzer/Compiling and Analyzer/Running to try out the code.
Git References
Hall C wiki Git_Howto page
We will try to follow the branching model described in: A successful Git branching model