CS61C Fall 2017 Lab 0 - git and Number Representation

Goals

Reading

Policies and Partners

You are REQUIRED to have a partner for lab checkoffs. This will reduce the number of check-offs we have to perform (allowing us to answer more of your questions) as well as give you someone to discuss class material with. BOTH partners will need to be present at check-off to receive credit and both partners will be asked to participate during the check-off. Try your best to find someone in your lab section with similar work habits as yourself.

How Checkoffs Work

You'll notice that at the end of (almost) every exercise, there is a section labelled "Check-off." The items in this section are what you must successfully demonstrate to your TA in order to receive credit for completing the lab. Once you and your partner finish ALL of the exercises, you should put your names AND logins on the checkoff list on the board, and a TA or Lab Assistant will come and check you off.

Labs in CS61C are graded out of 2 points. Labs are due for full points by the next lab session (which is 1 week after the lab was assigned). If they're another week late, then you get half credit. Any later than that and it's 0 points. You can always ask for help on the lab, but you can only asked to be checked off once. If you asked to be checked off and you don't pass the checkoff you'll get 0 points.

Exercises

In today's lab only, you should do exercises zero through two alone. You will need a partner for exercises three through five.

Exercise 0: Account and Environment Setup

To obtain your CS61C login, go to https://acropolis.cs.berkeley.edu/~account/webacct/ and login using your Calnet ID. Once you login, create a new account for CS61C. This should give you a username and a temporary password. Now, you can login to your instructional account by running the command ssh cs61c-xxx@hive1.cs.berkeley.edu on your laptop, and entering in your username (cs61c-xxx) and temporary password. Congratulations! You are now remotely accessing the hive1 computer located in Soda 330. You can also login directly onto one of the lab computers with that username and password.

In order to change your password from the temporary one, open another terminal window, and enter ssh update.cs.berkeley.edu and follow the prompts.

Now you're ready to start the lab!

Checkoff:

Exercise 1: Bitbucket Account Setup

Please read the following instructions carefully before proceeding. Almost all issues students run into during this lab can be prevented by carefully following the steps provided. Even if you have experience with git from previous 61 series classes, the process we use to set up your accounts may be different in this class.

This semester, we will be requiring that you use git, a distributed version control system. Version control systems are better tools for sharing code than emailing files, using flash drives, or even other file sharing mechanisms like Dropbox.

We'll be using Bitbucket to host private repositories in which you'll store your code. If the previous sentence means nothing to you, don't be alarmed! We'll walk through the process shortly. But first, you'll need to create a Bitbucket account if you don't already have one.

Why Bitbucket? Bitbucket allows accounts to have unlimited private repos. GitHub limits this to 5 per (student) user. Since many of you have already used those 5, we decided to use Bitbucket. If you have expereince using Github.com in previous classes, don't worry: Bitbucket interacts with git in the same way as Github.com, it is just a different website for hosting the remote (online) repositories.

Setting up Bitbucket and creating a Bitbucket repository

Navigate to bitbucket.org

Setting up git

Now that we have created our repo, lets configure git so that it knows who you are. While logged into your instructional account (from part 0), Run the commands listed below, replacing YOUR NAME with your first and last name (inside quotes) and YOUR EMAIL ADDRESS with the email address you used to register for your Bitbucket account:

$ git config --global user.name "YOUR NAME"
$ git config --global user.email "YOUR EMAIL ADDRESS"

Checkoff:

Exercise 2: git, Remotes, and the Hive machines

First, some quick defintions.

Throughout this class, you will regularly work with three different computers that may very well have three different versions of your code. These three are your local machine (your personal computer), one of the hive machines (while logged into your instructional account), and a remote (your Bitbucket repositories). For the least pain throughout the semester, it's essential that you understand the difference between these three and how you can share code between them.

  1. Your local machine. Just your good ol' personal computer--nothing new here!
  2. The hive machines. We'll be using a lot of different software and libraries throughout this class that might require different versions than the ones on your local machine (e.g. python2.7 versus python3). Therefore, you'll need to log into your instructional account on a hive machine (hivexxx@cs.berkeley.edu) so that you can run your assignment code in an environment with all of the correct software/library versions.
  3. The Bitbucket remote. Your Bitbucket account serves a lot of purposes, but 2 of the most important are as 1) a way to share your code using git 2) a backup of your code, so that if something ever happens to your local machine, you can recover your code instead of having to start over! Conceptually, you can also think of the Bitbucket remote as another machine that only stores your project code (and doesn't do much else). You will push changes to Bitbucket (i.e. updating the files on Bitbucket) and also pull changes from Bitbucket (i.e. updating files on your local machine)

If you aren't already logged in, SSH onto the hive machine as in part 0. Next, obtain the files for this section.

Obtaining Lab Files

Copy the contents of ~cs61c/labs/01 to a suitable location in the home directory of your instructional account as follows.

$ mkdir labs (if ~/labs doesn't exist)
$ cp -r ~cs61c/labs/00/ ~/labs/00

You should be able to see the lab files if you navigate to "~/labs/00".

To copy the lab files to your local machine, you have two options. 1) You can use git and Bitbucket, which you'll learn in the next section, and allow you to have version control over the changes you make to your lab code. 2) Using the scp command, which requires less steps but does not give you version control. Read below on how to use scp for future labs, but for this lab, we'll be using git. If you already know how to use scp, feel free to ignore the following.

Scp follows the same semantics as the cp command used above (cp -r [host] [destination], -r being a flag to copy recursively all directories and files). Thus, one way to use scp to copy files to your local machine is to navigate to a place on your local machine that you want to store your lab files, and run scp -r cs61c-XXX@hiveXX.cs.berkeley.edu:~/labs/00 ./ (don't forget the "./" at the end for the destination argument). You must run this command from your local machine; it will not work if you run this on the instructional machines. If you then type ls, your lab folder should appear on your local machine.

Pushing to and pulling from Bitbucket

Now let's push some code to the Bitbucket "lab0_with_git" repo that you made earlier! Run the following list of commands, while inside your "~/labs/00" directory. 
git init # initalizes git to start tracking all changes within this repo (i.e directory and its subdirectories)
git remote add origin https://bitbucket.org/mybitbucketusername/lab0_with_git.git # Adds your Bitbucket as a remote to backup your code to
git status

After the last command, you should see some output in your terminal about untracked files.

Now let's commit your changes (i.e. all of these newly tracked files). Remember the following sequence of commands, you'll be using them regularly to commit changes to your code.

git add -A # stages all modified files for committing
git status # you should now see that files are staged
git commit -m "Commit message" # you can enter whatever you'd like for the message
git branch # you should see that only the master branch exists, and you're currently on it
git push origin master # this pushes your code to Bitbucket! You should now see it on Bitbucket.

Git's version control is built around commits, or checkpoints in development of different versions/stages of your code. To explain the above steps a little further:

When it comes to git, if you're ever unsure of something, but just want to make sure you have a saved copy of the current contents of your code, just run git add and then git commit .

Now that we've got your code stored on Bitbucket, let's get your code on your local machine and actually start modifying it. Open a terminal window on your local machine, and navigate to the directory where you'd like to store your labs on your local machines (e.g. "~/cs61c/labs"). Now run the following command.

git clone https://bitbucket.org/mybitbucketusername/lab0_with_git.git

Just like that, the lab0 files you had on your instructional account and on Bitbucket are now also on your local machine! Now, let's make some changes. Within the lab0_with_git directory, open the hello.sh file. Change student_name from "Oski" to your own name, and change line 14 from ls to sl. Then, try running the file with ./hello.sh. You should see some greetings printed out, and a message that the sl command was not found. Not so interesting, huh? This is one of the situations where the hive machines have different things installed than on your local machine. Let's use git to get your newly changed code onto a hive machine, so that you can run hello.sh as expected! Run the following commands:

git add hello.sh
git commit -m "Write your own commit message"
git push origin master

Now open up the terminal window where you were logged onto a hive machine (back from part 0). Navigate to the directory where you originally copied the lab files, "~/labs/00", and then run: 

git pull origin master

You may be presented with a new screen asking you to write a commit message. This is likely the built in text editor Vim. To start editing your message, first type :i, write your commit message, and then type :wq to save your message and exit the editor.

This command fetches any new changes/updates to the branch "master" that have been stored on the remote "origin", and then merges them onto the current branch of your non-remote copy of your code (in this case on your instructional account). So just like that, the name and "sl" changes that you made earlier on your laptop, are now also present on your instructional account. Now, again run ./hello.sh. Cool train, eh?

One last git command that you'll find useful is git log . Run this command, and you'll see a history of all the commits ever made to your code (on the current branch), including the time and who made the commit.

Checkoff:

Exercise 3: Working on Projects with Partners

This semester, you'll be allowed to work with a partner on projects, but how can you smoothly change code in the same files without having to email files back and forth? Git to the rescue! In this part, you'll learn the process for every project for obtaining the starter files for the project and then also collaboratively working on the code with your partner. For the rest of this part, choose one partner to be Partner 0 and the other to be Partner 1. You can do this part either on your laptop or on your instructional account.

Setup: Getting the Project Files

First, let's make a Bitbucket repo to store your proejct code. Partner 0: Follow the steps from part 1 again in order to create a new Bitbucket repo with the necessary sharing permissions, but this time name the repo "lab0-xxx-yyy", where "xxx" and "yyy" are your logins in alphabetical order (e.g. "lab0-abc-adf"). Share the repo with Partner 1's Bitbucket account.

Now both partners, navigate to the directory where you'd like to store your project code (e.g. "~/cs61c/projects" or "~/projects"), and run the following commands:

git clone https://bitbucket.org/mybitbucketusername/lab0-xxx-yyy.git
cd lab0-xxx-yyy
git remote add lab0-starter https://github.com/61c-teach/fa17-lab0.git
git fetch lab0-starter
git merge lab0-starter/lab0 -m "merge lab0 skeleton code"

You saw most of these commands in Part 2. git pull is actually a shorthand for running the last two commands. git fetch fetches any changes/updates from the remote specified, in this case "lab0-starter", and git merge then merges those changes on branch "lab0" into your current local branch (which is "master").

Both partners should now have the starter code for this part on their machines.

Branches: Working on the same file at the same time

Branches are super useful for working on code with other people, as each person can have their own branch to make their changes on. It also allows for the branch "master" to be the sort of "final draft" version of your project code. Let's create a branch for each partner to work on. Run the following command, replacing branch name with "partner0" or "partner1" depending on which partner you are. 

  git checkout -b "branchName"

Next, each partner should open up foo.py. Change the partner names and complete the functions according to your partner number (i.e. if you're partner 0, then complete zero_func, if you're partner 1, then complete one_func). Afterwards, commit your changes and verify that the commit succeeded with:

git add foo.py
git commit -m "Commit Message"
git log

Now, let's merge the changes you just made with your "master" branch: 

git checkout master # switches you from the "partnerX" branch to the "master" branch
git merge partnerX # merges all changes from the "partnerX" branch into your current branch (i.e. master)

Generally, when working on projects (not just for this class), we suggest following this process of creating a new branch for whatever new changes you're trying to make. Then, you can work on those changes on this branch until you get everything to work, and then actually merge those changes and modify the "master" branch.

Now, let's share your changes with your partner! According to your partner number, and in this exact order, run the following commands (each command after the colon). 

0: git push origin master # partner 0 pushes their changes to Bitbucket
1: git pull origin master # partner 1 pulls those changes and has both partners changes in their current files 
1: git push origin master # partner 1 pushes their files to Bitbucket
0: git pull origin master # partner 0 pulls those updates and has all of the changes too

Both partners should now try running foo.py, and you should see the sequence of pulls/pushes you both just performed. In general, when Partner A wants to share their changes to a branch with Partner B: 

A: git push origin [branchName]
B: git pull origin [branchName]

Merge Conflicts: When collaboration goes wrong

In the previous section, each partner was able to merge the changes into their code because each partner worked on different lines of the file. Partner 0 worked on "zero_func", while Partner 1 worked on "one_func". Generally, as long as you work on different lines of the same file, git will be able to reconcile the changes to the different sections of the file. However, in some cases, you and your partner might modify the same line(s) in a file and then try to merge your modifications to the same line. This situation is called a merge conflict, and poses a problem because git doesn't know whose modifications it should accept for the conflicting line(s). Let's see how to resolve this.

First, we need some modifications to work with. Run the following commands and modify baz.py according to your partner number. 

  git checkout -b part3
### Fill in baz.py according to your partner number. ###
git add baz.py
git commit -m "Commit message"
git checkout master
git merge part3

Next, let's have Partner 0 again push up their changes, and Partner 1 pull those changes. 

0: git push origin master
1: git pull origin master

Oh no Partner 1, you have a merge conflict! If you open up baz.py, you'll notice that around line 12, some arrows and other numbers have been added by git to signify a merge conflict. The top half (before the "========") is your Partner 1 changes, and the bottom half is the code from the remote (i.e. the change that Partner 0 just pushed). Resolve the conflict by deleting the ">>>>", "======", and the commit numbers (next to the arrows), and leaving only the name of one of the professors. You now need to re-add the once-conflicted file and commit it: 

1: git add baz.py
1: git commit -m "Resolved merge conflict"
1: git push origin master

Partner 0 can now pull the changes: 

0: git pull origin master (will add commit message)

If both partners run baz.py, you should both see the same thing outputted.

Checkoff:

Exercise 4: Binary Alphabet

Let's take 4-bit numbers. If we stack five 4-bit numbers on top of each other in binary, we can make patterns and pictures! To help visualize this, you can think of 0's and 1's as white and black instead. For example, what does the following bit pattern look like?

0 1 1 0  □ ■ ■ □
1 0 0 1  ■ □ □ ■
1 1 1 1 -->  ■ ■ ■ ■
1 0 0 1  ■ □ □ ■
1 0 0 1  ■ □ □ ■

Checkoff:

Exercise 5: 1,000 $1 Bills

I hand you a thousand $1 bills and ten envelopes. Your job is to find a way to put various numbers of dollar bills in those ten envelopes so that no matter what amount of money I ask you for (between $1-1000), you can simply hand me some combination of envelopes and always be assured of giving me the correct amount of cash.

Checkoff: