CPSC 035: Lab 1: Gitting Started

Due on Wednesday, September 16th (by the end of the day, U.S. Eastern Daylight Time).

Overview

In this lab, you will:

  • Set up a work environment for CS35 on your computer.

  • Learn how to use Git, a popular version control system.

  • Write a C++ program using files and arrays.

Please read this lab carefully as it prepares you for all of the labs you will be completing this semester and includes instructions for making sure that you have submitted your work properly!

Part I: Setting Up

Throughout this semester, you will complete your CS35 lab assignments using computers on the Swarthmore Computer Science network. These computers have been preconfigured for use in our classes and provide a consistent experimental environment. Instead of physically gathering in the computer lab this semester, we will set up your own personal computer to allow it to store files and run programs on our CS lab computers.

This setup process involves several steps. They are not especially complex, but they take a little while. You don’t have to complete the entire process at once, but we recommend you proceed in the following order.

  1. You will need a way of sending commands to the CS network computers. To do this, we will use a piece of software called an SSH client. The SSH guide will help you install this. If you are not familiar with how to use the SSH terminal, please see the Using Unix tutorial on the CS website to get familiar with it.

  2. You will need to be able to access the files on your CS network account. Although the files are stored on the CS network, you can work with them as if they are on your computer using an SSHFS client. The SSHFS guide shows you how to install that software.

  3. Your lab assignment is stored in a Git repository which we discuss below. To access your assignment, you will need to follow the one-time setup instructions for Git on the CS network by connecting using the SSH client from step 1. Please note that these are one-time instructions for your account: if you have already set up Git (because, for instance, you have taken CS31), you won’t need to repeat these steps for this semester.

  4. You will need a way to work on your source code. There are a number of editors available to you, but we are recommending that you download and install Visual Studio Code for this semester. Later in the semester, we will show you how to install plugins in Visual Studio Code that let you work directly with your partner by simultaneously editing the same source code files.

Once you have completed the setup steps in the above guide, you are ready to work on your CS35 lab assignments! This is the lengthiest setup process you will have to do for any CS35 lab. The rest of this lab write-up shows you how to use the above tools to work on your assignment.

Part II: Gitting Started

As mentioned above, we will be using a version control system known as Git. The purpose of a version control system is to track changes to software over time. Each week, you will use Git in this class to submit your homework.

We will learn about Git throughout the course of the semester. This part of the lab will teach you just what you need to know to complete the first few assignments.

About Git

Git Logo

A Git repository is a directory containing files that are managed by Git. This looks just like a normal directory under most circumstances, but it contains a hidden .git subdirectory (that you generally shouldn’t touch). By using the git command inside of a repository, you can manage the files in that directory.

Git is a distributed version control system: there can be multiple different copies of the same repository on different computers, some of which might contain different information than others. When developing software, we occasionally use the git tool to move information from one copy of a repository to another. Two operations you’ll be performing in this lab are cloning (which creates a copy of a repository) and pushing (which sends your changes back to the original repository).

About GitHub

GitHub Logo GitHub Logo

GitHub is a popular website that stores and manages Git repositories. Software developers can keep their repository on GitHub and then copy content to and from it from their own computers. We will not be using that website, although we will be using something very similar. Instead, we will use Swarthmore’s own GitHub site at https://github.swarthmore.edu.

Cloning a Repository

For the labs in this course, you will be using repositories that we have already created; this is similar to how students use the update21 script in CS21 to fetch the initial files for a given assignment. That repository — the directory of files we have created for you — exists on the Swarthmore GitHub site. To edit those files, you will have to clone the repository into your home directory on the CS lab machines. You can make the clone by running this command:

git clone git@github.swarthmore.edu:cs35-f20/lab01-<your-username>.git

Make sure to replace <your-username> with your Swarthmore username. For instance, you might write

git clone git@github.swarthmore.edu:cs35-f20/lab01-zpalmer2.git

if your Swarthmore username were zpalmer2. (It isn’t.)

Running the clone command will cause git to create a directory named e.g. lab01-zpalmer2 in your current directory. You should cd into that directory now.

Setting Up Your Editor

Your newly-cloned repository contains several files. We will focus on editing Questions.txt now. Since you will often want to edit many different files while working on a lab assignment, we will set up Visual Studio Code to show you the entire repository. Note that we will rely heavily upon the SSHFS client that we set up before.

If you are using a Windows computer, please make sure that S: is working correctly by opening it in your file explorer. If you are using a MacOS computer, please run the SSHFS connection script in your Documents folder. Either way, you should then open Visual Studio Code.

Once the editor window is open, you should then open a file browser and go to your CS network home directory. If you followed the SSHFS tutorial, then this will be your S: on Windows or the SwatCS device in your Documents folder on MacOS. Find the folder containing your lab repository and drag it into your Visual Studio Code editor window as seen in the screenshots below.

Dragging Repository Folder: Windows

Dragging Repository Folder: MacOS

Once you drag the folder into the editor window, it will be added to your workspace. You can open files by clicking them as they appear on the left.

Editing Files

Pencil and Paper

OpenClipArt.org

Now that your editor is working, you should open the Questions.txt file and answer the questions it contains.

Once you are finished, run git status from your SSH client. You should see something like this:

On branch master
Your branch is up-to-date with 'origin/master'.
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   Questions.txt

no changes added to commit (use "git add" and/or "git commit -a")

This indicates that changes have been made to the file named Questions.txt but that Git has not yet been told about those changes. In order to record the changes that we have made, we must commit them. Run the following commands:

git add Questions.txt
git status

You should now see something like this:

On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	modified:   Questions.txt

This indicates that Questions.txt has now been "staged"; that is, it will be part of the next set of changes we create. In a more complicated scenario, we might want to run git add several times or do something else more complicated to create a single "change". We use git add to add the changes for certain files to the staging area in order to create a new version of our directory.

In this case, the only file we’re changing is Questions.txt, so we’re ready to create our change. Run the following command:

git commit -m "Answered the questions."

This command will create and record the change. It will attach the comment (here, "Answered the questions.") to the new versions of our files. If we run git status now, we see something like this:

On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

The message "working directory clean" indicates that our Git repository knows about all of the changes that we’ve made. You can even look at the history of the changes you have made by running git log. (If you do, you can exit the log viewer by pressing q.)

Pushing Your Changes

Package

OpenClipArt.org

Remember: your directory on the CS network is only a copy of the "real" repository stored on the Swarthmore GitHub site! At this point, your copied repository is aware of your new changes, but the Swarthmore GitHub version is not. We can see this because the previous git status message included "Your branch is ahead of 'origin/master' by 1 commit.", which tells us that we have a commit that the GitHub does not. To send the commit that we have made to the Swarthmore GitHub, we can run git push.

Counting objects: 3, done.
Writing objects: 100% (3/3), 209 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To git@github.swarthmore.edu:cs35-s20/lab01-jbrody1.git
 * [new branch]      master -> master

Now, git status looks like this:

On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

The git push command attempts to send every new commit we have made back to the original place from which we cloned our repository.

Double-Checking Your Push

To be certain that the Swarthmore GitHub website has your changes, visit your repository on that webpage. The URL will be https://github.swarthmore.edu/cs35-f20/lab01-<your-username> (again replacing <your-username> appropriately). If everything worked out, you should be able to view the GitHub copy of Questions.txt by clicking on the like-named Questions.txt on that page. Make sure that the contents of that file match what you expect.

Summary

In order to use Git to update your lab repository, you should perform the following steps:

  1. Clone the repository (only necessary once per lab!)

  2. Make changes to your files

  3. git add each file you changed

  4. git commit -m "message" to create a commit

  5. git push to send your changes to the Swarthmore GitHub

  6. Repeat steps 2-5 as necessary until you are satisfied with your repository

Part III: Number Summaries

Next, you will create a C++ program to read a list of numbers from a file and produce some summary information from it. You will submit your work by pushing it to the Swarthomre GitHub repository. Remember: we will only grade what appears in the GitHub repository, so make sure to git push!

The Task

C++ Logo

brandsoftheworld.com

Your task is to create a program which performs the following steps:

  • Prompts the user for the name of a file.

  • Reads the contents of that file — a sequence of numbers — into an array.

  • Prints out a series of summaries regarding that sequence.

The files you will read all have the same format. The first number appearing in the file indicates how many numbers the file contains. The rest of the numbers in the file are the numbers to summarize. For instance, if a file contains

4
5 10 18 3

then the sequence we want to read contains the four numbers 5, 10, 18, and 3. You are guaranteed that all of the numbers in the file are non-negative; you are also guaranteed that there are at least two numbers.

Once you have read all of the numbers in the file, you should print the following summaries:

  • The last number in the sequence (here, 3).

  • The largest number in the sequence (here, 18).

  • The number of items in the sequence that are less than 10 (here, 2).

  • The average of all of the numbers in the sequence using a double (here, 9.0). If you used a float instead of a double, that is fine.

You are required to write at least three functions other than main to complete this task. Those functions should not print any values; they should return information for main to print.

You should compile your program using the following command:

clang++ -std=c++11 -o numberSummary numberSummary.cpp

Then, you can run your program with this command:

./numberSummary

Example

Here are two example runs of the above program:

  • Please enter the name of your file: test_data/numbers1.txt
The last number is 2.
The largest number is 9.
There are 4 numbers less than 10 in the sequence.
The average is 6.

  • Please enter the name of your file: test_data/numbers3.txt
The last number is 57.
The largest number is 99.
There are 5 numbers less than 10 in the sequence.
The average is 45.8.

Your output doesn’t have to look exactly like this, but it should produce the same results.

Approaching the Task

It’s always good to plan out what you intend to write before you write it. What functions will you need? How will you read and store your data?

In this assignment, we have the following suggestions:

  • Start by opening the file and reading the first number, which tells you how many elements are in the sequence. Then, you can dynamically allocate an array large enough to hold them all.

  • Don’t try to do everything at once. For example, you might start by reading all of the numbers into an array and then simply print them all back out again. You don’t have to keep the code that prints the numbers out, but this will help you be sure that you read them in properly before you do anything more complex with them.

  • Many CS35 students took CS21 at Swarthmore. In that class, we discuss Top-Down Design (TDD), a strategy where we outline the program before we complete it. Decide what functions you want to write. What inputs should they take? What should they return? What is the purpose of each function? Answer all of these questions before implementing the functions.

  • Every time you get something useful written, then git add, git commit and git push! You can push as many times as you want and each push is a copy of your work. If you later find that you’ve made changes you regret, you can always go back to an old version that GitHub will keep for you.

Comment Your Code

As you implement your lab, provide comments describing what each piece of code does.

/* don't forget includes here */
#include <iostream>

using namespace std;

/* sayHello
 * a simple function that prints a greeting
 *   @param name: the name of the person we're greeting
 *   @return: nothing
 */
void sayHello(string name) {
  cout << "Hello " << name << endl;
}

...

Remember to Add, Commit and Push

Once you are finished writing the above program, remember to add, commit and push! You can double-check your submission by looking at the GitHub website. We will grade what is shown there by the due date.

Lab Reflection

Once you have completed the lab, please fill out the lab reflection. This will usually take less than a minute and is part of your participation grade.

Zachary Palmer and Michael Wehar, Swarthmore College, 2020