Using the Git Software Tool on the Peregrine System
Learn how to set up and use the Git software tool for development on the Peregrine system.
Tool Set Up
For using the git tool, learn how to:
Day-to-Day Tool Use
Before you can get access to the git server, you'll want to set up your account. You'll also want a copy of your ssh public key; the ".ssh/id_rsa.pub" file.
As of April, 2013, Scientific Computing has switched to NREL's Github Enterprise server for internally-managed repos. For more information on how to use NREL's git repositories, see the NREL Git HowTo document (missing file) (requires VPN access and password).
To get ready to use NREL's git server, you simply have to log in to https://github.nrel.gov/ with your NREL userID and password.
If you have a problem logging in: please contact the IS Service Desk at x4171, or 303-275-4171. Please note that github.nrel.gov ONLY WORKS if you are on the NREL network (or VPN.) It is not available externally.
For example, you could create a local working copy of the "test_repo" repo (puts it in a folder in your current directory):
git clone email@example.com:kbendl/test_repo.git
Now, make changes to whatever you need to work on.
Recommendation: commit your changes often, e.g., whenever you have a workable chunk of work completed.
git add <filename(s)-you-changed>
git commit -m "A comment about the changes you just made."
If you collaborate with others in this repo, you'll want to pull their changes into your copy of the repo. You may want to do this first-thing when you sit down to work on something to minimize the number of merges you'll need to handle.
# ...to be checked into your repo later
git add README.txt
git commit -m 'first commit'
git remote add origin git@hpc/my.projectname.git
git push origin master
# ...and want to push it to a git repo on the server.
git remote add origin firstname.lastname@example.org:hpc/my.projectname.git
git push origin master
# you may want to stick this in your local repos .git/config
remote - origin
merge - refs/heads/master
Find the commit you want to reset to:
Once you have the hash:
git reset --hard <hash>
And to push onto the remote:
git push -f <remote> <branch>
Advanced Tool Use
You want to work on a new feature, but don't want to mess-up the master while testing your ideas. In git, you can do this with a branch. Here are some git branch notes outlining what might be a typical branch workflow.
Create a local branch called "experimental" based on the current master...
git branch experimental
Use your branch
(start working on that experimental branch....)
git checkout experimental
git pull origin experimental
# work, work, work, commit....
Send local branch to the repo
git push origin experimental
Get the remote repo and the branches...
git fetch origin
Switch to the experimental branch....
git checkout --track origin/experimental
merge the branch into master....
git checkout master
git merge experimental
Once you've merged a branch and you are done with it, you can delete it.
git branch --delete <branchName> # deletes branchName from your local repo
git push origin --delete <branchName> # deletes the remote branch if you pushed it to the remote server
If there are conflicts, git adds >>>> and <<<<< markers in files to mark where you need to fix/merge your code. Examine your code with git diff:
Make any updates needed, then git add and git commit your changes. Admittedly, there's a lot more to merging than this. Contact HPC Support if you need more details about merging and handling merge conflicts.
All done? You can delete the branch (a couple of different ways)
git push REMOTENAME :BRANCHNAME
Although this is a bit arcane, it essentially pushes 'nothing' into branchname
git push origin :experimental
destroys the branch....
git branch -D experimental
If you realize that someone broke some code in the past, you can use git log to see when the commits happened, and then git diff has some options that can help.
What changed between two commits (hopefully back to back commits):
git diff 57357fd9..4f890708 > my.patch
Just the files that changed:
git diff --name-only 57357fd9 4f890708
You can tag a set of code in git, and use a specific tagged version.
git tags -l
Set a tag
git tag -a "2.2" -m"Tagging current rev at 2.2"
Push your tag
There may be an extra step you'll want to take to ensure your tags make it up to the git server.
git push --tags
use tag tagname....
git checkout tagname
What if you realize that you don't want to keep your changes to the important_code.py file? How can you easily un-modify it — revert it back to what it looked like when you last committed (or initially cloned, or however you got it into your working directory)? Luckily, git status tells you how to do that, too. In the last example output, the unstaged area looks like this:
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
# modified: important_code.py
It tells you pretty explicitly how to discard the changes you've made (at least, the newer versions of Git, 1.6.1 and later, do this — if you have an older version, we highly recommend upgrading it to get some of these nicer usability features). Let's do what it says:
$ git checkout -- important_code.py
$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage) #
# modified: README.txt #
You can see that the changes have been reverted. You should also realize that this is a dangerous command: any changes you made to that file are gone — you just copied another file over it. Don't ever use this command unless you absolutely know that you don't want the file.
Let's say you were working on some code that you'd checked-out from a repo on some other server, say from github.com or something. Now, you want to check that code into NREL's repository. Once you've requested a new NREL git repo and it's configured, you can:
git remote set-url origin email@example.com:hpc/my.<strongnewprojectname.git
See git help remote for more details or you can just edit .git/config and change the URLs there. You're not in any danger of losing history unless you do something very silly, If you're worried, just make a copy of your repo, since your repo is your history.
You can export a copy of your code to your $HOME directory using the following command:
git archive master --prefix=my.projectname/ --output=~/my.projectname.tgz
Using github.nrel.com or github.com and always have to type your password? To not have to type your password every time you push/pull to the repo in github, you have to add your ssh key(s) in your github profile and change the remote URL to use SSH instead of https. To do this:
- Copy the content of ~/.ssh/id_rsa.pub
- Click on: your git ID > Edit your Profile > SSH Keys > Add SSH Key
- Paste the content of ~/.ssh/id_rsa.pub into the "Add an SSH Key" window
Then, in your local git repo directory, type:
git remote set-url origin firstname.lastname@example.org:hpc/my.projectname.git
After doing this, you should not have to type your password every time.