Software Design and Implementation
CS 251 (SD), Fall 2018
We will use a system called git
for electronic
submissions in this
course. Git
was originally designed for managing the
Linux source code
by Linus Torvalds, the creator of Linux. Git
has since become
extremely popular for sharing and collaboratively developing code,
often through the free GitHub service. Instead of GitHub, we will use
a local git
server named stogit
, in order to
make the work you submit
available to graders and professors for the course but otherwise
private.
Contents:
Appendix - setting up a
git
working directory manually.
Overview
The git
system operates as a web service: you do work
on a desktop or laptop computer, then store or retrieve your work using a
git
server via the Internet. We will use the
git
server named stogit
, located at the web URL
.
stogit.cs.stolaf.edu
Your desktop or laptop is called your local computer, and
the stogit
computer is called a remote computer.
The CS program creates a
stogit
repository located on thestogit
server for each student in a course. Yourstogit
repository is the (remote) saved version of your code, and is accessible only by you and by your TAs and professors in your course. For team projects, a separatestogit
repository will be created with shared access by the team members.Git
is designed for teamwork: team members can do software development work separately, then integrate their (working) code with previous working code.Your
stogit
repository for this course namedsd-f19
/usernameusername
is your username (e.g.,smith99
).For homework, labs, projects, etc., you will typically do your work on a Link computer (RNS 202 or 203) in a subdirectory of your
directory. Your~/SD
~/SD
directory on your local computer is called your working directory.From time to time as you work, you can make a "snapshot" of your files in your (local) working directory, called a
commit
ingit
. Thesecommit
snapshots record of your progress at a certain point of code development.It's possible to retrieve versions of your code files from prior
commit
s if you find you need to return to a previous state.When you have working code for some stage of your program, you can synchronize a
commit
snapshot with your remotestogit
repository across the network, using thepull/push
process:first
pull
from yourstogit
repository, to check for any (remote) repository changes relative to the files in your (local) working directory; thenpush
yourcommit
snapshot to your (remote)stogit
repository
Thereafter, you could retrieve the changes you
push
ed tostogit
, even if you accidentally delete or corrupt the code in your (local) working directory.
Key terms for talking about
git
We use these terms (introduced above) when talking about
git
and our stogit
server.
local - ______
remote - ______
repository - ______
working directory - ______
commit
(snapshot) - ______pull/push
- ______
Setting up a local client computer for stogit
Setting up a local "client" computer to use stogit
for
your course requires two steps:
creating an
ssh
key for safe passwordless connection to thestogit
server; andestablishing a working directory for your
stogit
repository.
Notes:
Step 1. only needs to be performed once per client computer; also, since all Link computers share your same home directory
~
, you only need to carry out these steps once on one Link computer in order to usegit
on any of the Link computers. But if you want to accessstogit
from another computer that has git software installed (e.g., maybe your laptop), you need to perform Step 1 on that computer.Step 2. needs to be performed once per
stogit
repository. For example, if you have both a personal course repository and a team project repository, you will need to perform step 2. for both of those repositories.
Step 1. Creating and entering an
ssh
key for stogit
When you connect from your local computer to
stogit
, you need to authenticate (prove who you
are, e.g., with a password). It can get very tedious to have to enter
your password over and over for frequent stogit
interactions, so
stogit
provides a convenient way to authenticate that is actually
more secure than using passwords directly (because the authentication data is
far harder guess than a password is). The system is called
passwordless ssh
, and you can set it up using
these steps:
Create an
ssh
key. You may already have anssh
key on the Link computers: if you already have a file~/.ssh/id_rsa.pub
, you can skip to step b. below. Otherwise, generate a newssh
key as follows.link% ssh-keygen -t rsa
Note: Thessh-keygen
command will prompt for an optional "passphrase" - you can enter an empty line for your passphrase.Note: The string
link%
indicates that this command should be entered in a terminal window on a Link computer. Don't enter the characterslink%
.Enter your
ssh
key into yourstogit
settings. Visit
in a browser, and log in using your St. Olaf username (e.g.,stogit.cs.stolaf.edu
smith99
) and password. Open yourSettings
(look for a drop-down menu in the upper right corner of thestogit
web page, then chooseSettings
), then select "SSH Keys" from the menu bar. Give a name to your key (such as "Link machines"), then copy and paste the public key (contents of the.pub
file above) into the larger text box. Finally, click the submit button for your key.In order to copy your public key, you can print it at a terminal window on a link machine using, e.g.,
link% cat ~/.ssh/id_rsa.pub
Note: Your
stogit
profile can hold multiplessh
keys for access from various client computers, but you need only enter onessh
key from a single Link computer in order to accessstogit
from any Link computers. This is because all Link computers share your same home-directory files.First, make some git configuration settings on the computer, if you haven't already (e.g., for a prior course).
Notes:
These commands are illustrated here for Link computers; you only have to configure one Link computer, and all others will share that configuration.
If you are using a new non-Link computer, e.g., a Raspberry Pi, these commands must be entered on that new computer, whether or not you have entered them on a Link computer.
git config --global user.name "Your Name" git config --global user.email "username@stolaf.edu" git config --global core.editor "emacs"
If you already have files in a subdirectory
~/SD
, e.g., from prior assignments, rename that directory in order to protect that work.link% mv
~/SD
~/SD
.buNow create your new working directory.
link% git clone git@stogit.cs.stolaf.edu:
.gitsd-f19
/username~/SD
link% ls~/SD
Note: This creates a new directory
. If~/SD
is a never-used repository, your working directory should now contain a single filesd-f19
/username
that contains some simple identifying information (check this).~/SD
/READMEFinally, copy your prior work (if any) to your new working directory
.~/SD
link% cp -r
~/SD
.bu/*~/SD
link% ls~/SD
The
ls
command should showREADME
(from your repository) and also all your prior work (from
.~/SD
.bu- Create or modify some code files in your (local) working directory.
Use
git add filename ...
to stage files intended for acommit
snapshot.Use
git commit ...
to create acommit
snapshot.Use
git pull ...
to check for any (remote) repository changes.Use
git push ...
to upload yourcommit
to thestogit
server.Steps 1 and 2: Create a
commit
(snapshot) of files in your working directory.This means to record the current state of those files, stored on the local system (not yet on
stogit
).Commit
s can bepush
ed to your repository onstogit
(which explains why we are making thiscommit
), and can also be used to retrieve previous versions of your work.Staging the files to
commit
. First, usegit add
to indicate which files to include in thiscommit
. For example, if you want tocommit
files namedhw1.txt
andhw1.out
contained in a directory
, you can enterenter~/SD
/hw1link% cd
You could accomplish the same thing using these commands.~/SD
/hw1 link% git add hw1.txt hw1.outlink% cd
Alternatively, you could use~/SD
link% git add hw1/hw1.txt hw1/hw1.outgit add hw1
instead ofgit add hw1/hw1.txt hw1/hw1.out
above, but that would submit all files in the
subdirectory, which may be too much.~/SD
/hw1For example, in C or C++ programming, only
.c
or.cpp
files should be committed (unless instructed otherwise), not executables or other files that can be generated from the source files ending in.c
or.cpp
.
The
git add
command records current versions of the files you indicated, in preparation for acommit
. Those versions are referred to as staged files.-
Note: Git commands such as
git add
,git commit
,git pull
, andgit push
may be entered within a subdirectory of your working directly. Enter them wherever it's convenient; for example,cd ~/SD/hw1 git add hw1.txt hw1.out ...
may be more convenient thancd ~/SD git add hw1/hw1.txt hw1/hw1.out ...
To view the files that are currently staged (and unstaged) enter
link% git status
Note: If you stage a file withgit add
, then make more changes in that file in your working directory,git status
will list that file as being both staged (the version of that file when youadd
ed it) and unstaged (the current version after your subsequent changes).
Creating a
commit
. Now you can create thecommit
"snapshot" consisting of your staged files usinglink% git commit -m "message"
wheremessage
describes what thiscommit
contains. For example, if you are submittinghw2
, a good message might be "submit hw2 complete" or "hw2, part A only", e.g.,link% git commit -m "submit hw2 complete"
The
message
is the easiest way to label yourcommit
s, so you (and your graders!) can know whichcommit
s contain which files.
Steps 3 and 4: Uploading a
commit
to your remote repository onstogit
usingpush
.Since
git commit
only creates local snapshots of your work (on your computer only), you need to perform an operation calledgit push
operation to upload your work to the remotestogit
repository.pull
the current version of your remote repository. This step retrieves any current versions of files stored in yourstogit
repository. Since we're assuming it's new, your remote repository
initially contains only a single file calledsd-f19
/usernameREADME
.link% git pull origin master
retrieves thatREADME
file. Here,origin
refers to yourremote
, andmaster
indicates the main (and only)branch
of that remote repository. (Git branch
es help with team project development and other advanced tasks; using the one main branchmaster
is enough for now.)Get in the habit of always pulling before you push.
The
git pull
command firstfetch
es the files from the remote repository to your local.git
structure, then attempts tomerge
yourcommit
with thosefetch
ed files. This could result in a conflict; for example,git
would detect a conflict if your working directory has a fileREADME
that differs substantially from a fileREADME
that wasfetch
ed from the remote repository.If such a merging conflict arises, the output from
git pull
will inform you about it. Anymerge
conflicts must be resolved before you can proceed.Performing the
push
. Now,push
yourcommit
to your remote repository onstogit
.link% git push origin master
You should always
pull
just before youpush
tostogit
. Thegit pull
command retrieves any changes in the remote repository, thus helping to avoidpush
ing out of date code to the remotestogit
repository.Get in the habit of
pull
ing before everypush
from the beginning. You won't notice a difference if you're the only person using a repository, but you need to have this habit in place before you share a repository in a team project.
Now, enter the following
git
configuration commands.link% git config --global user.name "Your Name" link% git config --global user.email "username@stolaf.edu" link% git config --global core.editor "emacs"
for your personal name and St. Olaf username.Initialize the working directory for
git
.link% cd
The~/SD
link% git initgit init
command creates agit
structure in your current directory, implemented in a new subdirectory.git
. (If you ever need to remove thegit
structure from a directory, you can delete the.git
subdirectory.)Note: We will assume that your default directory is your working directory
~/SD
(the one containing the.git
subdirectory) for allgit
commands below.Assign a
git
name to your remote repository.link% git remote add origin git@stogit.cs.stolaf.edu:
This command assigns the name
.gitsd-f19
/usernameorigin
to your repository onstogit
. Such names are referred to asremote
s ingit
. You can choose a name other thanorigin
, butorigin
is the typical name for a singleremote
when getting started, and we will use that name in our examples.Be sure to enter the URL accurately. For example, be sure to use a colon instead of a slash just after
stogit.cs.stolaf.edu
. Also, use your username, not the eight characters "username
." You can check your current remote (if any) usinglink% git remote -v
If you need to correct your remote, delete it and add again.link% git remote remove origin link% git remote add origin git@stogit.cs.stolaf.edu:
.gitsd-f19
/username
Note: It is also possible to interact with
stogit
using a
different method, called HTTP (instead of SSH), but this requires
you to enter a
password every time you interact with the remote stogit
server
from the command line. We recommend using the SSH approach
described above, since it is more convenient (not needing to enter
your password frequently) and more secure (your password isn't
transmitted over the network).
Step 2. Establish a working directory for your
stogit
repository.
The basic git
work cycle
Once you have successfully set up your working directory for your
stogit
repository (in Part
B), you will follow a standard git
work cycle to
create and modify your code, package it in commit
s as
you go, and pull/push
working commit
s to
stogit
, as indicated in the Overview section above. The
basic work cycle has five steps, including four git
commands:
The following items elaborate on this four-part work cycle.
Appendix
Here are the steps of the stogit_wd
command found
on Link computers. You can perform these manually on a non-Link
computer in order to set that computer up as a client for
stogit
.
The instructions for initializing a working directory vary
depending on circumstances such as whether that directory already
exists and whether it contains files you want to add to your
git
repository. We will start with the typical
circumstances for a first submission of work in a course, explaining
the steps of the procedure as we go, then
describe variant procedures for initializing a git
working
directory in some other circumstances.
Case 1: A non-empty directory of your work already exists, and
you have a new stogit
repository for that work.
We will assume that the directory is named ~/SD
, and that your stogit
repository is named
. sd-f19
/username
Case 2: To create a new (local) working directory and load it with a copy of your (remote) repository. ______
______Case 3: A non-empty directory of your work already exists, and
you want to add that work to a non-empty stogit
repository.
______