Home
>>    




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:

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 the stogit server for each student in a course. Your stogit 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 separate stogit 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 named 

    sd-f19/username
    where username 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 ~/SD directory. Your ~/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 in git. These commit snapshots record of your progress at a certain point of code development.

    It's possible to retrieve versions of your code files from prior commits 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 remote stogit repository across the network, using the pull/push process:

    1. first pull from your stogit repository, to check for any (remote) repository changes relative to the files in your (local) working directory; then

    2. push your commit snapshot to your (remote) stogit repository

    Thereafter, you could retrieve the changes you pushed to stogit, 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:

  1. creating an ssh key for safe passwordless connection to the stogit server; and

  2. establishing 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 use git on any of the Link computers. But if you want to access stogit 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:

  1. Create an ssh key. You may already have an ssh 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 new ssh key as follows. 

    link%  ssh-keygen -t rsa
    Note: The ssh-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 characters link% .

  2. Enter your ssh key into your stogit settings. Visit stogit.cs.stolaf.edu in a browser, and log in using your St. Olaf username (e.g., smith99) and password. Open your Settings (look for a drop-down menu in the upper right corner of the stogit web page, then choose Settings), 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 multiple ssh keys for access from various client computers, but you need only enter one ssh key from a single Link computer in order to access stogit from any Link computers. This is because all Link computers share your same home-directory files.

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.

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

    On a Link machine: 
    git config --global user.name "Your Name"
git config --global user.email "username@stolaf.edu"
git config --global core.editor "emacs"

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

  3. Now create your new working directory. 

    link%   git  clone  git@stogit.cs.stolaf.edu:sd-f19/username.git  ~/SD
link%   ls  ~/SD

    Note: This creates a new directory ~/SD . If sd-f19/username is a never-used repository, your working directory should now contain a single file ~/SD/README that contains some simple identifying information (check this).

  4. Finally, 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 show README (from your repository) and also all your prior work (from ~/SD.bu .

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 commits as you go, and pull/push working commits to stogit, as indicated in the Overview section above. The basic work cycle has five steps, including four git commands:

  1. Create or modify some code files in your (local) working directory.

  2. Use git add filename ... to stage files intended for a commit snapshot.

  3. Use git commit ... to create a commit snapshot.

  4. Use git pull ... to check for any (remote) repository changes.

  5. Use git push ... to upload your commit to the stogit server.

The following items elaborate on this four-part work cycle.

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). Commits can be pushed to your repository on stogit (which explains why we are making this commit), and can also be used to retrieve previous versions of your work.

  • Staging the files to commit. First, use git add to indicate which files to include in this commit. For example, if you want to commit files named hw1.txt and hw1.out contained in a directory ~/SD/hw1 , you can enterenter 

    link%  cd ~/SD/hw1 
link%  git add hw1.txt hw1.out
    You could accomplish the same thing using these commands. 
    link%  cd ~/SD 
link%  git add hw1/hw1.txt hw1/hw1.out
    Alternatively, you could use git add hw1 instead of git add hw1/hw1.txt hw1/hw1.out above, but that would submit all files in the ~/SD/hw1 subdirectory, which may be too much.

    • For 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 a commit. Those versions are referred to as staged files.

    • Note: Git commands such as git add, git commit, git pull, and git 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 than 
      cd ~/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 with git 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 you added it) and unstaged (the current version after your subsequent changes).

  • Creating a commit. Now you can create the commit "snapshot" consisting of your staged files using 

    link%  git commit -m "message"
    where message describes what this commit contains. For example, if you are submitting hw2, 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 your commits, so you (and your graders!) can know which commits contain which files.

Steps 3 and 4: Uploading a commit to your remote repository on stogit using push.

Since git commit only creates local snapshots of your work (on your computer only), you need to perform an operation called git push operation to upload your work to the remote stogit repository.

  1. pull the current version of your remote repository. This step retrieves any current versions of files stored in your stogit repository. Since we're assuming it's new, your remote repository sd-f19/username initially contains only a single file called README. 

    link%  git pull origin master
    retrieves that README file. Here, origin refers to your remote, and master indicates the main (and only) branch of that remote repository. (Git branches help with team project development and other advanced tasks; using the one main branch master is enough for now.)

    Get in the habit of always pulling before you push.

    The git pull command first fetches the files from the remote repository to your local .git structure, then attempts to merge your commit with those fetched files. This could result in a conflict; for example, git would detect a conflict if your working directory has a file README that differs substantially from a file README that was fetched from the remote repository.

    If such a merging conflict arises, the output from git pull will inform you about it. Any merge conflicts must be resolved before you can proceed.

  2. Performing the push. Now, push your commit to your remote repository on stogit. 

    link%  git push origin master

    You should always pull just before you push to stogit. The git pull command retrieves any changes in the remote repository, thus helping to avoid pushing out of date code to the remote stogit repository.

    Get in the habit of pulling before every push 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.

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.

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

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

    1. Initialize the working directory for git. 

      link%  cd ~/SD 
link%  git init
      The git init command creates a git structure in your current directory, implemented in a new subdirectory .git . (If you ever need to remove the git 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 all git commands below.

    2. Assign a git name to your remote repository. 

      link%  git remote add origin git@stogit.cs.stolaf.edu:sd-f19/username.git
      This command assigns the name origin to your repository on stogit. Such names are referred to as remotes in git. You can choose a name other than origin, but origin is the typical name for a single remote 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) using 

      link%  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:sd-f19/username.git

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




rab@stolaf.edu, May 3, 2021