This is the base upstream repository for CSCI 460.

This repository is mostly intended to contain examples from class and serve as an example GitHub repository for students.

Also, to use GitHub effectively in this class we require a rather particular way of setting things up. Below I outline how you can setup two repositories: one private and one public. Your private repo will be where you check in your solo work (early programming assignments) and for our grading. Your public repo can be used to contribute things back to this class repo.

These instructions are adapted from CSCI 366 (Systems Programming) @ Montana State University. Many thanks to Carson Gross for paving the way. In fact, there are some videos from 366 that may be useful if this is confusing to you (below). Make sure you follow OUR directions below though - remember, this is CSCI 460, not CSCI 366 :-)

1. Setting Up Your Git Repositories
2. GitHub Repo Diagram Explained

1. Please follow the steps in the Setup Your PRIVATE Repo (via Clone) section below.
   • Create an SSH identity (see Setup Your SSH Identity below).
2. Please follow the steps in the Setup Your PUBLIC Repo (via Fork) section below.
3. Please follow the steps in the Register Your PRIVATE Repo (via Pull Request) section below.
4. Check out additional info in the Other Things To Know section.

NOTE: My examples are all based on a Unix-y terminal running atop macOS. If you use a different OS (e.g., Windows) your mileage may vary.

Your private repository will be used for your individual work and our grading. Unfortunately, GitHub doesn't let you fork a repo and then make it private. Thus, rather than the traditional Forking model, we are going to use a Copy model for the class. Please use the following steps to create a PRIVATE version of this repo for your work:

• Create a private repository in your own account by
  • Going to https://github.com/new
  • Enter the name csci-460-fall2020-private
  • Select Private
  • Navigate to the Settings -> Manage Access section
  • Add traviswpeters (Travis's GitHub handle) and reesep (Reese's GitHub handle) as collaborators
• Now run the following git commands, substituting your GitHub username and NetID where required:

$ git clone https://github.com/traviswpeters/cs460-code.git csci-460-fall2020-private
$ cd csci-460-fall2020-private
$ git remote set-url origin [email protected]:<YOUR-GITHUB-USERNAME>/csci-460-fall2020-private.git
$ git remote add upstream https://github.com/traviswpeters/cs460-code.git

You now have a private copy of the repository on GitHub. You can push and pull to this repository with the standard git pull and git push commands.

When you want to get an update from the public class repository you can run this command:

$ git pull upstream master

You might want to do this at least each week, but likely before each class.

Your public repository can be used for contributing back to the class repository and to register your private repository. Please fork this repository to your personal account.

DO NOT PUSH YOUR INDIVIDUAL WORK CODE TO THIS REPOSITORY

In your forked copy of the class repo (the public version), please add a file to the /repos directory that is named

<YOUR NET ID>.txt

with the git URL of your private repository.

For example, if I were a student with the NetID W43m513 and my GitHub username was studentIAm I would add a file named W43m513.txt to /repos with the following line:

[email protected]:studentIAm/csci-460-fall2020-private.git

And then create a pull request against this repository.

We will accept the pull request, and your private work repo will be registered for the class at that point.

In CSCI 460 it is highly recommended that students DO NOT clone their public fork of this repository to their local system. This is to avoid confusion between your public and private repos. If this applies to you (i.e., you are prone to confusion), you should know that there is no need to have the public repo on your local system; you can edit files in the public repository via the web interface and submit pull requests there too.

Setting up an SSH identity makes it possible for you to interact with GitHub repos via the command line without having to re-enter your password all the time. If you've already setup an SSH key to have passwordless access to GitHub on the command line, you can probably skip this step. You can check to see if you have a key setup by looking in your ~/.ssh/ directory. If there is nothing there, or if you don't have a key dedicated to using with GitHub, you should read on.

You should then be able to copy/paste the public key to GitHub.

This article has more details on that process: Adding a new SSH key to your GitHub account

Once you've created your private repository, you can create separate directories for each assignment. Each programming assignment should be kept in its own directory (/pa0, /pa1, /pa2, etc.). Please do your solo work in the appropriate homework directory. Remember, DO NOT PUSH YOUR INDIVIDUAL WORK CODE TO THE PUBLIC REPOSITORY

Each week we will likely look at different code examples. These code examples help us practice tools we use, help us to understand how an OS implements something, etc. For weeks with code examples, a new directory (weekN) will be added to help us organize our examples.

The most important file here IMHO is our class Vagrantfile. This file contains the configuration for the VM we are using in this class.

In class we've talked about using shared folders to share files between your host OS and your guest OS. Once you know you've cloned the repo to your local system you can add a line like this to your Vagrantfile:

config.vm.synced_folder "/Users/myHome/dir/where/I/work/cs460-code", "/home/vagrant/code"
# Note that we are using the absolute path here.
# I've had mixed results with using symbols that expand to the correct directory
# (E.g., '~' for 'home directory). Try at your own risk...

Now when we access our VM, there should be a directory (~/code) in the VM that is synchronized between the host and guest.

This will enable you to, for example, edit code in your preferred editor on your host, and compile/run code on the guest.

At the very least, however, means that your code is not actually stored on the VM; code is stored on your host. This enables you to delete (vagrant destroy) your VM, create a new VM, and pick right up where you left off with your work.

WARNING: This means you need to make sure you never save files that you want to keep directly to the VM. Important files should be stored on the host and version-controlled with Git/GitHub.

We have encountered a few issues with VMs not compiling software correctly, etc.

If this happens to you, I first recommend re-running the Vagrantfile's provisioning steps and rebooting your VM.

This can be done by running the following commands from your host OS in the directory with your Vagrantfile:

vagrant provision
vagrant reload

If something seems out of place, try this step.

This is the VM/vagrant version of "Have you tried turning it off and on again?" :-)

A more extreme approach - which should be totally acceptable so long as you keep all of your files that you want to keep in a synced/shared folder! - is to run:

vagrant destroy
vagrant up

If you don't have the most up-to-date version of Guest Additions installed for your VM, it is possible that your VM may "drift" and become out of sync with the host. Put another way, it will be one time on your host OS and another time on your guest OS. This can be problematic for software that uses time / the timestamps of files in its logic. (Think make and Makefiles.)

There is a nifty vagrant plugin I use to help keep my VMs configured with the correct version of Guest Additions.

vagrant plugin install vagrant-vbguest

Then reboot the VM.

This should work. If you still have issues with time syncing between your host/guest, DM me and we can discuss more - I have a few other tricks up my sleeve :-)