Working with GitHub

Credit: The information on this site comes almost entirely from https://education.github.com/.

Git Overview

Git is an open-source, distributed version control software. Check out its wiki page for more information on why to use it and what it can do. Git was initially created by Linus Torvalds (but subsequently had many core developpers) for Linux.

GitHub is a company that implements a web-based version of git: it has a nice web interface and also a place for you to put your projects "into the cloud". GitHub offers all the functionality of git and adss some of its own (like wiki pages for each project, and social-networking-like features like feeds and followers). GitHub has 20+ million users, and it's becoming a virtual meeting place for software developpers, for sharing information and showcasing projects.

In a nutshell, a version control system lets you and your peers work and collaborate on projects, from anywhere. Initially you (or someone else) will create a remote master repository on github for your project. This master repository is hosted remotely, on github. You (and your partners, if any) will then clone (checkout) a private copy of the remote master repository on your local machine. You can clone several copies of the master repo in several locations, if you want. You can make changes to your local copy. When you are done, you stage these changes for commit, and then you push them to the master repository. Once your changes are pushed to the master repo, your partners can get them by "pulling" the changes from the master repo into their local repo. Git automatically merges the changes pulled form the master with the local changes in the local repo. Finally, git has a feature where it keeps a record of all changes, and any change can be recovered and reverted.

GitHub classroom

We will be using GitHub classroom. This is a layer on top of GitHub, that allows everyone in the class to clone private versions of the projects. To use it, you need to have a GitHub account. A free account will be fine; With a free account all your data and projects will be public, ie viewable by everyone. Your class projects will be private through the private class account that I've created for the class.

Using SSH keys

SSH is a secure protocol used to connect to a remote linux server. SSH stands for Secure SHell. SSH clients authenticate via passwords (less secure and not recommended, malicious users can break them) or SSH keys (very secure).

An SSH-key consists of a private key and a public key. The public key can be shared with anyone, and the private key needs to be kept confidential (just like a password).

To authenticate using an SSH-key, a user must have an SSH key pair on their local computer. The remote server (in our case, GitHub) will need to know the public key of the user who will want to authenticate. The user will need to copy her public key to the server, in the user's home directory at ~/.SSH/authorized_keys. This fill contains all the public keys that are authorized to log into this account.

How it works:

When the user (the client) wants to connect to the server (the host) vis SSH key authentication, it will send her public key to the host.
The host will check the authorized_keys file for the public key, it will generate a random string and it will encrypt it with using the public key. This encrypted message can only be decrypted with the associated private key.
The host will send this encrypted message to the user's client to test whether they actually have the associated private key.
The client will decrypt the message using the private key and obtain the random string, and send it back to the host.
The server had the original string and it can determine that the client must have the private key.

Using a SSH keys with a passphrase: With SSH-keys, if someone gains access to your computer, they also get access to all systems that authenticate you based on your SSH-key. To add an extra layer of security, you can add a passphrase to your SSH-key. The passphrase is used to encrypt the private SSH-key. Using passphrases is strongly encouraged to reduce the risk of private keys accidentally leaking (e.g. retired hard drives). Using a passphrase provides a second layer of authentication.

If you want to know more about SSH keys, there are lots of resources online; for example SSH essentials at DiGitalOcean.com.

Adding your SSH-key to an SSH agent to avoid typing the passphrase

If you have an passphrase on your private SSH key, you will be prompted to enter the passphrase every time you use it to connect to a remote host. You can configure your SSH-agent and add you SSH-key to avoid typing the passphrase everytime you need to authenticate. In a nutshell, you'll need to:

start an SSH-agent (use eval $(ssh-agent); this will start the agent in the background)
add your private key to the agent (use ssh-add)

See below.

Setting up you SSH key

You do not need to use SSH keys with GitHub, but it is strongly recommended for security and convenience, so better get it over with.

Checking if you have an existing SSH key.
Open a terminal, and:
```
$ls -al ~/.ssh
```
Check out the listing to see if you have a key. By default, the names of public keys are id_rsa.pub (or ...). If you see an id_rsa.pub file, it means you already have a public key. If you don't see one, then go to the next step and generate one.
Generating a new SSH key: In the terminal, use the ssh-keygen command.
SSH keys are 2048 bits by default. This is considered good enough for security. To specify a larger number of bits, include the -b argument followed by the number of bits you would like.
```
$ssh-keygen -t rsa -b 4096 -C "youremail@bowdoin.edu" 
```
This uses the RSA algorithm and creates a new public/private SSH key pair on your computer, using the provided email as a label. When it prompts you to enter a file to save the key, press Enter to accept the default. AT the next prompt, type a secure passphrase. A passphrase should be hard to guess, have at least 15 characters, contain a combination if letters and diGits and punctuation characters.
This has generated an RSA SSH key pair, located in the .ssh hidden directory in your home directory. These files are:
```
~/.ssh/id_rsa    <------------ the private key. DO NOT SHARE!!!
~/.ssh/id_rsa.pub   <--------- the associate public key. This can be shared freely 
```
If you generated a passphrase for a private key and you want to change it or remove it, you can do so with the ssh-keygen -p command.
Start the SSH-agent in the background
```
$eval "(ssh-agent -s)"
```
On my platform this shows:
```
SSH_AUTH_SOCK=/var/folders/vj/z8bp4njs7sjgjn8dlz7xjcwh0000gp/T//ssh-S4FdGNnegrbK/agent.47635;
export SSH_AUTH_SOCK;
SSH_AGENT_PID=47646; export SSH_AGENT_PID;
echo Agent pid 47646;
```
SSH-agent is a program that runs in the background and keeps your SSH-key loaded in memory, so you don't need to enter your passphrase everytime you need to use the key.
Modify your ~/.ssh/config file to automatically load keys into the SSH-agent and store passphrases in your keychain. You can do this with your favorite editor (for e.g. nano, atom, emacs, vim).
```
Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_rsa
```
Add your SSH private key to the SSH-agent and store your passphrase in the keychain. If you created your key with a different name, or if you are adding an existing key that has a different name, replace id_rsa in the command with the name of your private key file.
```
$ ssh-add -K ~/.ssh/id_rsa
```

Adding your SSH key to your GitHub account

First you need to copy the SSH-key to your clipboard; you can use the pbcopy command, as below (or you can open the file ~/.ssh/id_rsa.pub in your favorite editor and copy it; or....there are other ways..).

pbcopy < ~/.ssh/id_rsa.pub

Now go to you GitHub account page. In the upper-right corner, click your profile photo and click Settings. Click SSH and GPG keys. Click "New SSH key". In the In the "Title" field, add a descriptive label for the new key. For example, if you're using a personal Mac, you might call this key "Personal MacBook Air". Paste your key into the "Key" field. Click Add SSH key.

Initial Git setup

Before you starting using the Git command on the command line, you need to give it a basic configuration. This will tell Git who you are, making it easy for you and your partners to identify who committed code to your shared repository. Replace the email and name strings with your email address and name. If you have not run these commands, then the very first Git commit will fail and tell you to run them.

git config --global user.email "username@bowdoin.edu"
git config --global user.name "Your Name"
git config --global push.default simple

Working with Git

First, you'll clone the master repository. Assume someone gives you a link for a GitHib repository. For example, here is the repository which holds a Helloworld program: https://github.com/lauratoma/helloworld.git First you will go to the path where you want to place your local directory:

cd path-where-you-want-your-local-repo

Then you'll presumably create a directory to hold your local repo:

mkdir git-helloworld

Then you'll go to that directory:

cd git-helloworld

And finally you'll clone it

git clone https://github.com/lauratoma/helloworld.git

Once cloned, the usual work cycle in Git is pull-edit-commit-push-repeat:

Always start by pulling the most recent version from the master (if you don't have a partner, this is not necessary unless you pushed changes from a different repo; but it's always safe to do it).
```
cd path-for-your-local-repo
cd git-helloworld
git pull
```
Now your local repo is sync-ed with the master repo.
Now you can start working on the project, edit files, create new files. When you are done do a git status to find out the status of your repo:
```
git status
```
this will show you what files are modified.
Now stage the files that you want to commit:
```
git add file-which-you-want-to-commit
```
For example let's say you modified helloworld.c.
```
git add helloworld.c
```
You should never add object files and executables to the repo.
Commit to your local repo with git commit.
```
git commit -m "describe what the changes represent"
```
Note that commit does not take file names as arguments, and will update the local repo with the files that have been staged. Files that have not been specifically staged for commit, will not be commited.
Push the changes to the master repo with git push.
```
git push 
```

Again, git push does not take file names as arguments. Git push will sync the master repo with the commited files in the local repo.

That's it! We'll push branching later (pardon the pun).

Last modified: Thu Jan 25 11:16:27 EST 2018