______ Getting started with stogit (CS 273 (OS), Spring 2022)
Home
>>    




Getting started with stogit

CS 273 (OS), Spring 2022

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 

    os/s22/username
    where username is your username (e.g., smith999).

  • For homework, labs, projects, etc., you will typically do your work on a Link computer (RNS 202 or 203) in a subdirectory of your ~/OS directory. Your ~/OS 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 this step. 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., smith999) and password. Open your profile in the top right corner of the screen, select preferences , then select "SSH Keys" from the left 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.

Use the following git clone command (not mkdir) to create your working directory ~/OS. 

link% git clone git@stogit.cs.stolaf.edu:os/s22/username.git ~/OS

We have created a program called stogit_wd that simplifies the creation of a working directory and associating it with an existing stogit repository. This program is available for Link computers. To create working directories on other computers, you can manually perform the same steps that stogit_wd does, as described in the appendix.

To run stogit_wd on a Link computer, log in and start up a terminal window, then enter 

link%   source ~cs273/setup 
link%   stogit_wd  os/s22/username  ~/OS
If this is the first time you have used git on a Link computer, stogit_wd will prompt for your name. If something goes wrong with stogit_wd, the program will provide information and exit so you can work with a lab assistant or peer to make corrections and try the script again.

Note: Be sure to use lower case for the name of your repository os/s22/username, and to substitute your username (e.g., smith999) in place of username.

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 ~/OS/hw1 , you can enterenter 

    link%  cd ~/OS/hw1 
link%  git add hw1.txt hw1.out
    You could accomplish the same thing using these commands. 
    link%  cd ~/OS 
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 ~/OS/hw1 subdirectory, which is sometimes too much, especially for project submissions.

    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 os/s22/username initially contains only a single file called README. 

    link%  git pull origin main
    retrieves that README file. Here, origin refers to your remote, and main 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 main is enough for now.)

    Before summer 2021, the name of the main branch was master instead of main, but main is now the standard (and more inclusive) name for the main branch in git.

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

    link%  git push origin main

    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 ~/OS, and that your stogit repository is named
    os/s22/username.

    1. Initialize the working directory for git. 

      link%  cd ~/OS 
link%  git init
link%  git checkout -b main
link%  git branch -d master
      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.)

      The git checkout and git branch commands fix an issue with the older version of git init currently on Link machines. Here's an explanation for those who know about git branches (note that these commands work correctly only for newer repositories on stogit).

      • This version of git init assumes that the primary branch for a new repository is called master, but stogit (also github) now calls a new repository's primary branch by the name main.

      • The command git checkout -b main creates a new branch main and switches to that branch.

      • The command git branch -d master deletes the unwanted branch name master. Since master and the newly created branch main represent exactly the same files and commit history, no information is lost.

      Note: We will assume that your default directory is your working directory ~/OS (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:os/s22/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:os/s22/username.git

    Case 2: To create a new (local) working directory and load it with a copy of your (remote) repository. 

    link% git clone git@stogit.cs.stolaf.edu:os/s22/username.git ~/OS

    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, February 8, 2022