GitLab/ChiSubmit Submission Mechanics 2.0
In this class, we will be using two different software tools to manage homework submission: git and chisubmit. Along the way, you'll need to learn how to use ssh to log into remote machines, and a few other tools. Git is a widely deployed open source system for distributed version control. Chisubmit is a local product, which works together with GitLab (the UC CS git service) to facilitate homework submission and grading in CS classes.
Note that this page includes radically simplified procedures. Note that this new procedure does not use Box, disk images, etc.
First Time Set-up, CSIL Macs
Git, ChiSubmit, and ssh all use hidden “dot” files to store persistent information, like identity information and the location of upstream repositories. This is a problem on the CSIL Macs (which we use in this course), as they do not provide persistent storage. The CSIL staff has provided a small, but crucial workaround, in the form of SSH key-pairs that are persistant.
Setting up GitLab
Open a web browser, and navigate to https://mit.cs.uchicago.edu. Provide your CNetID and password, and you'll be logged onto the CS Department's GitLab server. You should have (at least) a couple of repositories there, beginning with the name “CMSC 16100.” Ignore the staging repository for now (it's used by the ChiSubmit system, but isn't something we'll ever fuss with). At the top of the screen, at the far right, will be an avatar icon (probably with a default gray profile), with a downward pointing triangle that indicates a hidden menu. Open that menu, and choose “Settings,” and then the “SSH Keys” tab from that page. Copy and paste the contents of .ssh/id_rsa.pub into the “Key” box, and press the “Add Key” button.
If you have an ssh key associated with the old “Box” solution, you can delete it, as you won't need that key pair again.
Cloning your repo
Return to the terminal, and clone your repo:
$ git clone git@mit.cs.uchicago.edu:cmsc16100-aut-18/USER.git cmsc-16100
Note that USER will be your CNet address, and you can simply paste in the complicated part (since you copied it in the previous step).
You'll get a warning that you've cloned an empty repo. That's right, you've cloned an empty repo. Intentionally.
At this point, you should make your repo the current working directory:
$ cd cmsc-16100 # of course, USER will be your CNetID
Setting up ChiSubmit
From within the cmsc-16100 directory that you just set up, run the command:
$ chisubmit init
Then follow your nose, e.g.,
Enter your chisubmit username [USER]:
Enter your chisubmit password: •••••••••••••••
You are a member of the following course(s).
Please select the one you want to use:
[1] cmsc16100-aut-18: CMSC 16100 - Autumn 2018
[X] Exit
Choose one: 1
The following directory has been set up to use chisubmit
for course 'cmsc16100-aut-18' (CMSC 16100 - Autumn 2018)
/Volumes/Courses/cmsc-16100
Remember to run chisubmit only inside this directory
(or any of its subdirectories)
First Time Set-up, Home Machines.
Setting up an RSA Key Pair
If you already have an ssh key-pair (if you already have an ~/.ssh directory with files id_rsa and id_rsa.pub, you do), you can skip this step. Otherwise, get a terminal program running (however this is done on your home machine), and
$ ssh-keygen
This will create a key-pair in ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub
Setting up GitLab
Follow the instructions for registering your public key ~/.ssh/id_rsa.pub with GitLab as above.
Decide where in your home file system you want to save your local repository. A reasonable location on a Macintosh would be ~/Documents/Courses/cmsc-16100, but you can make your own choice. You may need to create intermediate directories (like Courses in this example). Once you've set this up, clone your GitLab repo:
$ cd ~/Documents/Courses
$ git clone git@mit.cs.uchicago.edu:cmsc16100-aut-18/USER.git cmsc-16100
Setting up ChiSubmit
Unfortunately, setting up ChiSubmit on a personal computer is not at all straightforward. I recommend that you set up chisubmit on the CS department's Linux cluster. The following example assumes that you set up chisubmit in the ~/courses/cmsc-16100 directory, but again, you can make your own choice.
$ ssh USER@linux.cs.uchicago.edu
$ mkdir -p courses/cmsc-16100
$ cd courses/cmsc-16100
$ chisubmit init
and then proceed as above.
A Typical CSIL Working Session.
Once you've got all of this set up, a typical work session begins by cloning your repo to the local machine:
$ git clone git@mit.cs.uchicago.edu:cmsc16100-aut-18/USER.git cmsc-16100
$ cd cmsc-16100
This will give up an up-to-date local copy of the repository.
You'll do whatever work you need to do, and then from the cmsc-16100 directory, you'll commit the changes you've made:
$ git add .
$ git commit -m "An appropriate commit message, e.g., 'started on hw03.'"
$ git push
Then you'll dismount the virtual drive (by hitting the up arrow next to its name in a Finder window), and log out.
Submitting Homework and Labs
To manage grading, we use the ChiSubmit system, which is built on top of git. Each assignment will be given an particular name, e.g., hw01, or lab09. You'll create a directory with that name (exactly that name!) in the cmsc-16100 directory, and any files that make up that assignment inside that directory, e.g.,
$ chisubmit student assignment register hw01
$ mkdir hw01
$ cd hw01
$ vi ex1.1.hs # edit and test your work...
$ cd ..
$ git add .
$ git commit -m "completed hw01"
$ git push
$ chisubmit student assignment submit hw01
The new interactions here are at the beginning and the end. You use chisubmit student assignment register hw01 when you're starting to work on assignment hw01, and chisubmit student assignment submit hw01 (before the deadline) to submit it.
Note that you can resubmit work at any time before the deadline. Once the deadline passes, the assignment will be staged for grading.
A Typical Home Working Session
We modify the process above in two ways.
First, because you have a persistent local repo, you don't need to reclone it each time. Instead, cd to your local repo, and pull any changes that may have been pushed elsewhere (e.g., while working in the lab).
$ cd ~/Documents/Courses/cmsc-16100
$ git pull
Second, since you won't be able to run chisubmit on the local machine, so you'll run chisubmit on the CS department's Linux machines.
Register yourself as a one-person team (usually done before beginning work on an assignment):
$ ssh USER@linux.cs.uchicago.edu
$ chisubmit student assignment register hw01
And when you've completed, added, committed, and pushed the assignment, submit it:
$ ssh USER@linux.cs.uchicago.edu
$ chisubmit student assignment submit hw01
Note that there is no necessary link between the GitLab and Chisubmit directories—the coordination is done on the server side; and that the
*Why mit.cs.uchicago.edu? Surely it's not because we're naming the GitLab server after one of our competitors! No, it's because three servers were set up to facilitate the development of ChiSubmit, chi.cs.uchicago.edu, sub.cs.uchicago.edu, and mit.cs.uchicago.edu. The system was eventually deployed on the last of these three, mit, and documentation was stored on chi, but sub went away.