We are using Git to manage code repositories in this course. While this page will explain the basics in the context of completing labs for this course, please take a look at either the Git user’s manual or the CS-oriented overview of Git to learn more. Throughout the description on this page, we will be using the Util lab as a running example.

Cloning the Base xv6 Repository

$ git clone https://gitlab.oit.duke.edu/os-course/xv6-fall22.git
$ git clone git@gitlab.oit.duke.edu:os-course/xv6-fall22.git
Cloning into 'xv6-fall22'...
$ cd xv6-fall22

The above commands will clone the base xv6 repository, which will be used as the starting point for all projects in this course. Our repository differs slightly from the book’s xv6-riscv repository in order to simplify some aspects of the labs.

You can choose between using HTTPS (former) or SSH (latter) authentication for the Duke GitLab instance. SSH is easier, but you will need to create a public-private keypair and upload it to your GitLab profile. For more information on that process, please see the GitLab Profile Keys page.

Starting a Lab

You will use a separate branch for each lab, where all will be based on the base xv6 repository. You can create a branch for the Util lab by running:

$ git fetch
$ git checkout -b util origin/main
Switched to a new branch 'util'

The above command will create a new branch called util based on the base branch main. You can view the current status of your repository, including the active branch and any files changed by running:

$ git status
On branch util

Use git status often

Use git status often to understand the status of your repository before running commands.

Saving Your Progress

Let’s say you are finished with the first exercise in a lab and want to checkpoint your progress. You can commit your changes locally by running:

$ git commit -am 'finished exercise 1'
Created commit 60d2135: finished exercise 1
 1 files changed, 1 insertions(+), 0 deletions(-)

The above git commit command with the -a flag will automatically add all of your changes to tracked files into the commit. However, if you created a new file (e.g., countsys.c for a later exercise in the Util lab), you will need to explicitly add those as follows:

$ git add user/countsys.c

In order to save your work remotely, in case your local machine dies (RIP), you need to add another remote repository to push your committed changes to. You can create a personal GitLab repository on the GitLab Projects page, which you will log into with your Duke credentials. The project URL should be configured based on your own user ID and then a project name of your choice. The visbility for this repository should be Private, which is the default. Please uncheck Initialize repository with a README, as there is no need to initialize this repository.

Do not use public repositories

Please use personal (private) repositories on Duke’s GitLab instance to host your project files, and not publicly accessible spaces such as GitHub or non-private repositories on GitLab.

To add this as a remote repository and set this as your upstream repository for pushing commits on your current branch, run the following:

$ git remote add personal https://gitlab.oit.duke.edu/<UserID>/<ProjectName>.git
$ git push --set-upstream personal util
$ git remote add personal git@gitlab.oit.duke.edu:<UserID>/<ProjectName>.git
$ git push --set-upstream personal util
To gitlab.oit.duke.edu:<UserID>/<ProjectName>.git
 * [new branch]      util -> util
Branch 'util' set up to track remote branch 'util' from 'personal'.

You can view your remotes by running git remote -v, and you should also see this reflected in git status.

Keeping Track of Changes

You can keep track of your changes by using the git diff command. For example, git diff will display the changes to your code since your last commit, and git diff origin/main will display the changes relative to the initial xv6-fall22 code. Here, origin/main is the name of the git branch with the initial code you downloaded for the class.

Creating Submissions for Gradescope

When you are ready to submit your work to Gradescope to be automatically graded, you can run make gradescope which generates a submission.zip file that can be uploaded to Gradescope. This file should only contain the files that were changed as a result of completing the lab assignment. Make sure you are on the correct branch for your current lab, otherwise the submission files will not be correct.

If you are using the remote VCM infrastructure, you can use scp or rsync to download the zip file from your VCM instance.