3.2. Course Repository on Github

All course materials (including this guide) are available as a public repository on github. It is highly recommend that you learn to use git well enough to checkout and update a copy of the course materials on your own computer. Many exercises have sample source code which is most easily used if fetched via git rather than laboriously downloaded one file at a time from the course site. The course materials will continue to change during the semester so we will periodically ask you to update your local copy to an up-to-date version.

3.2.1. Basics

Git is a software tool for version control which provides the means to track changes in a set of files over time and share them with other people. We are using the free service offered by github to host the official upstream repository of the course materials. Github adds issue tracking and social coding features on top of the standard git repository service.

Students will not be pushing to this repository, although we welcome bug reports documenting any errors that may be submitted via the repository issue tracker.

There are many online tutorials related to git. Some good starting points follow:

Note that there are many different git clients available, ranging from the standard command line tools to visual GUI-based applications. Each has their merits; the visual interfaces are much more beginner-friendly, but some sophisticated operations are only possible from the command line, so many users will install both to use as needed.

Github offers their own native visual clients for Mac or Windows as GitHub Desktop.

The IDeATe cluster MacBook Pros should have three different git clients:

GitX.app GitX visual client for OS X
/opt/local/bin/git command line client provided via MacPorts
/usr/bin/git outdated command line client provided by Apple

3.2.2. Using the Course Repository

The first step is to clone the repository, which will create a local copy in a new folder on your local machine. If you are using a command line client, the command is follows:

git clone git@github.com:cmuphyscomp/16-223-f15

This will create a new folder named 16-223-f15 in the current folder.

If you are using the GitHub Desktop software, open the course repository on github in a browser and then select the “Clone in Desktop” button; you may then select the destination for the 16-223-f15 folder. If that doesn’t work, try dragging the URL from the browser and dropping it onto the GitHub Desktop application window.

The repository can be updated to the current version using pull, which will fetch the upstream changes and merge them into the local copy:

cd 16-223-f15
git pull

The cd command makes the repository folder current, and the git pull command performs the fetch and merge.

Note that if you have made incompatible changes, this may result in conflicts. Please refer to the git manual to learn how to create your own branches and resolve conflicts. The most common conflict problems are caused by modifying the course source files in-place. If you are not planning to keep your own revisions in version control, the recommended practice is to duplicate provided files before modifying them to minimize your trouble later.

3.2.3. SolidWorks Examples

We have an additional repository of sample CAD files for SolidWorks at PhysComp SolidWorks repository. This is not strictly required for the course but may be useful if you know or learn 3D CAD.

3.2.4. Advanced Usage

Experienced users of github may know they can fork a personal copy of a repository and submit pull requests containing suggested patches.

If you would like to submit a pull request pertaining to the exercises rather than the course guide, it would be easiest for us if you actually submit it against the upstream physcomp-f15 repository from which 16-223-f15 is derived.