Using git

Note: this file is intended for the HPC group at UND. Items will be specific to that groups work

ssh credentials

In order to access the git server, you will need to have an ssh keypair set up. If you don't already have one, it can be generated on any unix/linux box. Just enter:

	ssh-keygen

at a command prompt. Some systems may require you to specify a key type (dsa or rsa), using the -t option. Rsa is the standard.

The program will ask you for a location for the keys (default is the $HOME/.ssh directory), and a passphrase. If you enter a passphrase, you will have to supply it every time the keypair is used. If you do not enter a passphrase, the keypair will work without any other input. Keypairs with passphrases are considered more secure than ones without, since if your private key were to be stolen/copied the theif couldn't use it without the passphrase. Keyparis without passphrases can be used in automated things like scripts, so as always there are tradeoffs. As long as the private key is kept safe, the keypair is secure.

Once the keypair has been generated, it will appear in your $HOME/.ssh directory as the files id_rsa and id_rsa.pub. The file with the .pub extension is the 'public' key, which will be installed on the remote machine to allow access from the account that has the private key file in the $HOME/.ssh directory. The public key should be sent to Aaron for installation on the git server. Do not send the id_rsa file to anyone, it is your private key and needs to be kept secret! Make sure the file permissions are set to only allow you to read it.

If you would like to use the keypair to access accounts on other unix/linux boxes via ssh, simply copy the id_rsa.pub key to the remote machine, and add it to the end of the $HOME/.ssh/authorized_keys file. If the file doesn't exist, create it. If it does, just cat it and the new public key out and send the output to a new file, then rename that file. E.g.:

	On local machine:
		scp $HOME/.ssh/id_rsa.pub myaccount@remote.machine:newkey.pub

	On remote machine:
		cd $HOME/.ssh
		cat authorized_keys $HOME/newkey.pub > foo.txt
		mv foo.txt authorized_keys

You will now be able to log on to the remote machine without a password via ssh, or copy files via scp. If you generated your keypair with a passphrase, you will need to enter that passphrase when using ssh or scp.

Using git

To access and work on a git repository, you will first need to clone the repository to your local machine. You should make a suitable directory, change to that directory, and clone the repo using the git command. For example, to clone the git radar project repo to your machine, do this:

	git clone git@winterfell.und.edu:/opt/home/git/radar

This will create a subdirectory radar in your current directory and copy all the files from the repo into it. It will also set up git housekeeping files in that directory for later use. You will only need to do the clone command once, when you initially copy the repo to your computer (or if you erase the entire directory).

Working on files
You can now enter the subdirectory and modify the files within it to your hearts content. However these changes are not recorded by the git system until you tell it to. If you have made changes to the program and wish to share them, the first thing you need to do is to commit the changes to your own repository, which is the subdirectory on your local machine. The command to do this is:

	git commit -a

This tells git to record the changes to the files you've made into the local git repository. You will be placed into an editor to enter a comment for the commit. The comment is for other users to let them know about whatever changes you've made to the code. Git will not allow you to make the commit without the comment.

This only affects your own, private repository. To actually share the repo by placing it back on the git server so that everyone may access it, you need to do this:

	git push origin master

This will transmit the changes you made to the master server, making them available to every authorized user.

Note:
The first time you run 'git commit -a', the system will create a config file in your home directory (usually $HOME/.gitconfig). It will also tell you what it's putting in that configuration file. If you're using a workstation or laptop, the email address the program chooses for you will be based upon the machine name and most likely not be correct. The program helpfully tells you how to change that however. To change your email address in the config file, which is a good idea since that's used for tracking on the git server, use this:

	git config --global user.email <emailname@email.domain>

Your actual name can also be reconfigured:

	git config --global user.name "Your Name"

Also, if you've done a commit using the wrong name/email, you can ammend it after the fact:

	git commit --amend --author='Your Name <you@example.com>'

Caveat:
If you have added files in addition to what the oringal repo had, git will not automatically include them. To do that, you need to do a:

	git add .

before you do the commit. This assumes the files you're adding are in the local directory. If in a different directory, you replace the '.' with the path to the directory. After that is done you can check to see that the files will be added by using the status command:

	git status

Updating your repository
To pull the latest copy of the repo (e.g. when someone else has made a change and pushed it), use this command:

	git pull origin master

or just:

	git pull

This will pull the latest code from the server to your local repo.

Caveat:
If you have pulled from the server, made changes, committed those changes, and try to do a push while someone else has done a push after you've done your pull (in other words, you're trying to push a new version that isn't based on the current version of the code), git will not let you do this. You will first have to do a pull, merge your changes into the new files, and THEN do a push to put your modified code into the server.

The git program will provide man pages for any function if you enter:

	git <command> --help

Helpful Links

Many good help documents on using git at: https://help.github.com/