CS 161: Operating Systems (Spring 2017)

Tuesday/Thursday 1:00pm-2:30pm

Pierce 301

Using Github Classroom

You will be using the git tool and Github Classroom to manage version control for your assignments, and to submit those assignments to the course staff.

What is Git?

Git is a distributed version control system. A version control system (or source code management system) is a tool for storing the source files of a project, distributing them to developers working on the project, and coordinating changes made during development. A version control system stores not just the current state of the project, but all past states as well. This makes it an important tool both for collaboration and for historical investigation. (Often finding when a bug was introduced makes it much easier to diagnose and fix it.)

A distributed version control system does all this without requiring a central master server. Instead, each copy of the project contains the full change history and copies can be synchronized with each other to share updates.

Git is one of several available distributed version control systems; it was originally developed by Linus Torvalds for development of the Linux kernel. For information on how to use git, see A Guide to Git.

What is Github Classroom?

Github Classroom is an online git repository for use by educational institutions.

Signing up for Github Classroom

Before you can access the CS 161 repo on Github Classroom, you must sign up for a Github account if you do not already have one. This step, which is initiated via the Github Classroom web page (see the "Sign up" link), only needs to be performed once. Note that Github will require you to have a public/private key pair. If you already have a key pair, simply copy the pair into the ~/.ssh directory of your CS 161 VM. If you do NOT already have a key pair, then do the following:

Launch your VM.
Open a terminal.
Run ssh-keygen -t rsa and follow the instructions.
You have now created your ssh keys. They live in the directory ~/.ssh.
Now run cat .ssh/id_rsa.pub to display your public key.
Copy your public key (that is, select the text on the screen, and copy it to the clipboard), and enter it into the field on the Github Classroom page which asks for your SSH key. Be sure to click "Save"!

Managing Assignments

During the first week of the semester, you should clone our repository so you can begin viewing and understanding the code. Instructions to do this are below. Throughout the semester you will be modifying your clone and submitting assignments by allowing us access to your repository. Periodically, we may need to provide updates to your repositories. In these cases, we will instruct you to pull from the master to your clone.

It's important that you have a mental model of how all these clones interact.

There is a master repository owned by us that you will pull from but never push to. If we have new code for you or patches to the system, they will show up here. Also, if you end up needing to use a solution set, it will be available from this repository.
Assignment 1 is a solo assignment; each person in the class will use their own private clone of the CS 161 repo.
Assignments 2, 3, and 4 are group assignments, meaning that you and your partner will share a repo on Github Classroom.

Creating and Managing your Clones

As noted, you will be producing your own little clone army. Manage them well!

Creating your Initial Assignment 1 Clone on Github Classroom

Here's what to do:

Open a browser and navigate to this url.
Click the "Accept this assignment" button.
You should see a new page which says "You are ready to go!" The page will provide the link to your Assignment 1 repo, e.g., https://github.com/CS161/a1-your-name. Click on that link.
You will now see the homepage for your Assignment 1 repo. On the right side, you'll see a green button called "Clone or download." Click that button to see the clone path for your repo, e.g., git@github.com:CS161/a1-your-name.git.

At this point, you've created a clone on Github Classroom. Next, you'll want to create a clone on your virtual machine.

Launch your VM and open up a terminal.
Change into the ~/cs161 directory (you should create this directory if it doesn't already exist).

Configure your git "identity":

      git config --global user.name "FIRST_NAME LAST_NAME"
      git config --global user.email "YOUR_@COLLEGE_EMAIL"

Execute the following command:
```
      git clone REPO_URL os161
```
where REPO_URL is the clone path for your repo (see Step 4 above). You now have a new folder called ~/cs161/os161, which contains the entire distribution for OS/161.

Throughout the semester, when we want to distribute code to you, we will make it available in the staff-maintained CS 161 repository. It will make things easier if you have a shorthand for that repo; you can set that up now by issuing the following command, in your VM, from inside the os161 directory:

git remote add handout git@github.com:CS161/CS161-handout.git

This allows you to access our repository using the name handout for the rest of the semester.

Submitting problem sets

Each time you begin an assignment, tag your repository with the tag asstN-start, where N is the number of the assignment. When you are ready to submit, tag your repository with asstN-submit. Create tags using the following commands:

git tag asstN-start
git tag asstN-submit

Note that you cannot tag uncommitted changes, so you will want to first commit all your changes, then tag your repository and then finally push your changes back to your clone on Github Classroom by running:

git push origin master --tags

from your "os161" directory.

Please read the submit guide for more information.