Git Setup

Overview

Git is a distributed version control system to track and manage changes to files. This course uses Git for assignment distribution and submission.

Recommendations

We strongly encourage you to follow these 'best practices 🔗' for Git (or any version control systems). Although Git will be used in a somewhat limited scope in this class, it is beneficial to develop good habits early on.

• Learn about Git. A list of useful Git resources has been included below.

• Commit early and often. Having periodic checkpoints simplifies restoration in case of a catastrophic event and allows a full view of progress.

• Write useful commit messages. If anyone ever has to dig through your Git history, good commit messages will make their lives easier.

• Never check in broken code. Make sure that your code can always compile and run, even if you haven't implemented all the functionality.

• Test your code before committing. Please! Don't 'think' your code works after including some changes (even for something trivial as writing comments). Run some tests to ensure that it actually does.*

Organization and Workflow

You will be interacting with two repositories in this course:

1. Your personal repository under your NetID.

2. The release repository, release. This repository contains all lab assignments and machine problems for the course. Each individual assignment will be released under its own folder at an appropriate time.

Before the start of every assignment, the course staff will push assignments to the release repository. You will have to merge the newly pushed assignments into your own repository. Once you have completed working on the assignments, you will commit and push your submission. The course staff will grade your lastest submission before the late deadline and post your grades to a grade branch in your own repository.

To ensure that this workflow will work properly please follow the instructions below.

Git Resources

This course uses Git and Github as the primary means of distributing materials. If you are unfamiliar with git, please take a look at the links below to learn more about Git and its workflow:

• GitHub quickstart 🔗

• Git cheatsheet 🔗

• An interactive game about git 🔗

• Git transport commands and workflow 🔗

• Git online book 🔗

The above list is only a very small fraction of the Git resources that are available online. We encourage you to research other resources as well.

Course Setup

Follow instructions in this section to get set up for the course.

Create Repository

To create a repository for the class, first log in using your UIUC NetID and password at the following link (https://edu.cs.illinois.edu/create-gh-repo/ttYY_ece220/) to create a repository for this class. Replace tt with the term abbreviation (fa, sp, su for fall, spring, summer) and YY with the two-letter year abbreviation (19 for 2019). You will need to create a GitHub account. Follow the instructions carefully to set up your repository.

Now, if you navigate to https://github.com/illinois-cs-coursework/ttYY_ece220_NetID, replacing tt with the two-letter term abbreviation in lowercase (fa, su, sp) and YY with the two-digit year, you will see a repository under your NetID. You will be shown a page that shows the contents of your repository. Initially, this repository will be empty but don't worry about that because it will be populated soon.

Create a PAT (Personal Access Token)

In previous semesters, students were required to enter their username and password when using Github from the command line.

Github no longer allows for password authentication in the command line. Users are required to either use a Personal Access Token or SSH key for Github repositories.

In order to generate a token, go to your Github settings at https://github.com/settings/tokens 🔗, and click Generate new token.

Write any note, and set the expiration date for the token. You will be using this token through the whole semester, so it is recommended you set the expiration date at about 2-3 weeks after the last day of instruction this semester.

Check the repo box under the select scopes menu, and create the token.

Once you create the token, you will see the token as below.

The token is the string that begins with ghp_ - you will need this token throughout the semester, so copy it down immediately. If you accidentally leave the page without copying the token, delete the token and create a new one.

Then, click the Configure SSO dropdown menu, and click the Authorize button next to illinois-cs-coursework to allow you to use your token on UIUC repositories.

If you expect to use the same computer for assignments throughout the semester, it is recommended to set up an SSH key. Refer to those pages to set these methods up.

Clone Repository

On the upper-left side of the page, there is a button Code. Click on the button and make sure it says Clone with HTTPS. If not, click on the Use HTTPS text. Copy the link shown in the window, which should be of the form https://github.com/illinois-cs-coursework/ttYY_ece220_NetID.git, with tt replaced by the two-letter term abbreviation (sp, su, fa) and YY replaced by the two-digit year (e.g. 19 for 2019).

In a terminal, navigate to the location where you would like to keep your files for ECE220. Type the copied URL, with the NetID and ttYY fields filled in appropriately:

git clone https://github.com/illinois-cs-coursework/ttYY_ece220_NetID.git

You will be prompted to enter your username and password. Enter your Github username, and instead of your password, enter your Personal Access Token.

This will clone the remote repository to a directory on your computer where you will be able to retrieve/submit/work on assignments.

Add Release Remote

To retrieve assignments from the release repository, you have to add it as a remote (with the NetID and ttYY fields filled in appropriately):

cd ttYY_ece220_NetID
git remote add release https://github.com/illinois-cs-coursework/ttYY_ece220_.release.git

Check that the remote was added:

git remote -v

You should see four lines of output, two for origin and two for release

origin  git@github.com:illinois-cs-coursework/ttYY_ece220_NetID.git (fetch)
origin  git@github.com:illinois-cs-coursework/ttYY_ece220_NetID.git (push)
release https://github.com/illinois-cs-coursework/ttYY_ece220_.release.git (fetch)
release https://github.com/illinois-cs-coursework/ttYY_ece220_.release.git (push)

Configure Repository

It is important that you configure your repository correctly! If the following configuration parameters are not set, the auto-grader may not pull the correct versions of your submission and you may receive a lower score on your assignment. Regardless of which device you choose to work on your assignments (EWS and/or personal machines), please set the configuration parameters described below.

Set your name and email for your class repository, using lowercase letters only for the email:

git config user.name "Your Name"
git config user.email "NetID@illinois.edu"

Verify that your name and email have been correctly set:

git config --local --list

Retrieve Assignments

To retrieve (or update) released assignments, run:

git fetch release
git merge release/main -m "<some comment>" --allow-unrelated-histories
git push origin main

where <some comment> is a comment of your choice. The last command pushes the newly merged files to your remote repository. If something ever happens to your repository and you need to go back in time, you will be able to revert your repository to when you first retrieved an assignment.

Submit Assignments

To submit (or update) assignments, familiarize yourself with the process below.

There are a couple of states that files may be in as you are working on your assignment:

• unmodified tracked - files that are part of the local repository and have not had any changes made to them.

• modified tracked - files that are part of the local repository but have been changed.

• untracked - files that originally were not part of the local repository but have been created and are part of the workspace now. All the files that are pulled/merged into your local repository are already tracked.

To see all modified tracked and untracked files in your Git workspace, run:

git status

To stage any modified tracked or untracked files/directories for a commit, run:

git add <file/directory> <file/directory> ...

To commit any staged modified tracked or untracked files/directories to your local repository run:

git commit -a -m "<some comment>"

Rather than individually staging any modified tracked files, you can stage them all at once using the <-a> option with the above command. Note that this will not stage any untracked files. Which commands to use to stage files/directories depends on the situation. Individually staging files with git add gives you more control over which changes will be part of the next commit whereas using the <-a> option reduces the amount of typing necessary to stage all modified tracked files.

Finally, push the committed file/directories in your local repository to the remote repository with:

git push origin main

Verify that your submission are visible in the remote repository through a web browser. If you can see your changes, then the auto-grader can as well.

Grades

To avoid issues with having to pull code from the remote repository, a new branch called 'grade' will be created for you once the first assignment has been graded. You can view your grades through the web browser by navigating to https://github.com/illinois-cs-coursework/ttYY\_ece220\_NetID (replacing NetID with your own and substituting ttYY appropriately) and clicking on the button that says Branch: main. A drop-down with all available branches will appear. Click on the grade option. This will display a list of directories corresponding to each of your assignments. Inside these directories, you will find a grade.txt file with your score.

Authentication

Following the instructions above, every time you interact with the remote server, you will have to type in your username and Personal Access Token. To streamline this interaction and avoid typing your credentials, you can follow the instructions outlined at SSH Keys.