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:

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:

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.
  1. 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.

  2. 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.

  3. 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.

  4. 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
    

  5. 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 your Helloworld assignment:
https://classroom.github.com/a/3vGDBo9z
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://classroom.github.com/a/3vGDBo9z
Once cloned, the usual work cycle in Git is pull-edit-commit-push-repeat: 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: Tue Sep 5 10:25:44 EDT 2017