Setting up your ECEN 323 GitHub Repository

You will use GitHub for all labs in ECEN 323. You will create a GitHub repository that will serve two purposes: first, it will provide files for you that are necessary for completing the lab and second, you will use your repository to submit your files for the laboratory passoff. Because we will use GitHub extensively for the course, it is necessary for you to create a GitHub account and become familiar with it. This tutorial page will describe how GitHub will be used in this course along with examples and links to other usefule tutorials.

Before proceeding with this page, make sure you have a GitHub account and can log in to the GitHub page.

Create Class GitHub Repository

You will need to create a GitHub classroom repository (called a ‘repo’) for your ECEN 323 labs. This section describes how to create this repository. You will only need to create this repository once during the semester.

1. Create empty repo

Sign up for the repo by using the following link: https://classroom.github.com/a/iEOJkrbo. You must create your repository using this link, or the TAs will not be able to grade your code. This link will create an empty private repository on GitHub. You should see something like the image below:

After accepting your repo, your repository will be created (see image below).

2. Populate your repo

You new class repository will begin empty. Find this repo within GitHub by logging in to GitHub.com and browsing your repos. Once you find your class repo, click on it to view it. You should see a message something like the image below:

You will need to import “starter code” from the class starter repository to populate your repo.

Click the “Import Code” button at the bottom of this page. Enter the following URL in the box: https://github.com/byu-cpe/ecen323_student

At this point you have a private repository where you will store your laboratory files and perform your submissions. You can browse the files in your new repository using the GitHub web interface.

Adding a ssh key

In order to access a remote repository and clone it to your computer, you need to (1) setup a SSH key on your computer and (2) register this key with your GitHub repository. The first step in this process involves creating a public/private SSH key pair and adding it to your cost computer. Create a key by running the following command:

$ ssh-keygen

Press enter to save the key pair into the default .ssh/ subdirectory in your home directory. You should see the following prompt:

Enter passphrase (empty for no passphrase):

It is easier (but less secure) to leave the passphrase empty by pressing enter for the default “no passphrase”. You should then see the following output:

Your identification has been saved in /your_home/.ssh/id_rsa.
Your public key has been saved in /your_home/.ssh/id_rsa.pub.
The key fingerprint is:
a9:49:2e:2a:5e:33:3e:a9:de:4e:77:11:58:b6:90:26 username@remote_host
The key's randomart image is:
+--[ RSA 2048]----+
|     ..o         |
|   E o= .        |
|    o. o         |
|        ..       |
|      ..S        |
|     o o.        |
|   =o.+.         |
|. =++..          |
|o=++.            |
+-----------------+

At this point you have a public and private key that you can use to authenticate. This key is stored in your CAEDEM file space and should be able to access this key on any of the digital lab computers. More details on how to do this can be found at the following tutorial.

After creating a ssh key, you will need to add your public key to your GitHub account. This will authorize you to access your remote GitHub repositories on your computer without authentication. You can manually print your public key to the terminal by executing the following command:

$ cat ~/.ssh/id_rsa.pub

You will need to copy this key and paste it into a web page as described below. Go to https://github.com/settings/keys, and add your key to your Github account using the New SSH key button. You can view your newly created key using cat ~/.ssh/id_rsa.pub, then simply copy and paste into Github as described above. The following GitHub tutorial provides more details on how to do this.

Once you have created a SSH key on your computer and added this key to your GitHub repository, you are ready to clone your repository and interact with your respository on your host computer.

Cloning Your Class Repo

Once you have created your class repository in GitHub and created your SSH key, you will need to ‘clone’ the repo so that you can use it on the lab computers or on your personal computer. You can clone the repository on as many computers as you like. The following example demonstrates how to clone your respository into a directory named ‘ecen-323’.

git clone git@github.com:byu-ecen323-classroom/323-labs-<your_id>.git ~/ecen-323

Note that you will need to change the repository name to match your GitHub id. You can change the name of the destination directory to whatever you like or you can leave the destination directory empty to clone the repository into a new directory with the same name as the respository.

At this point you should have a new directory named ~/ecen-323 where your repository exists (you can name it whatever you want). Change into this directory to execute the next set of commands.

When you clone your repo, Git will create a ‘remote’ called origin that is connected to your private class repo. You should add a new remote that points back to the 323 starter code repository. This will allow you to retrieve any updates I make to the code provided to you. You need to add a remote to this starter code as follows:

git remote add startercode https://github.com/byu-cpe/ecen323_student

Adding this remote is a one time task that you should complete every time you clone your repository. You can view your remotes to verify both remotes (a remote to your private repo and a remote to the class starter code) by executing the git remote -v command:

$ git remote -v
origin	git@github.com:byu-ecen323-classroom/323-labs-wirthlin.git (fetch)
origin	git@github.com:byu-ecen323-classroom/323-labs-wirthlin.git (push)
startercode	https://github.com/byu-cpe/ecen323_Student (fetch)
startercode	https://github.com/byu-cpe/ecen323_Student (push)

Finally, configure your github repository to include your name and email. These settings will be used in the commit history of your repository.

git config --global user.name "Your Name"
git config --global user.email your_email@example.com

Updating Starter Code within Repostory

The starter code you imported into your repository when it was cloned contains code needed to complete each lab. This starter code will be updated frequently throughout the semester at the start of each lab assignment and to address problems that we find during the lab assignment. You will need to update this starter code at the beginning of each lab and when problems are found during the lab. Execute the following commands to ‘fetch’ the latest changes in the starter code and merge these changes into your repository:

git fetch startercode
git merge startercode/main -m 'Merge starter code'

After merging you will have a new ‘commit’ in your repository. This commit will be pushed to your remote repository next time you issue a ‘push’ command.

GitHub Submission

All lab submissions will be done through your Git repository. To complete a submission, you will need to create a ‘tag’ for the current commit in your repository. The following comands are used to tag your current commit with the string ‘lab1_submission’ and push the tag to the repository:

git tag lab1_submission
git push origin lab1_submission

This tag will point to your most recent commit of whichever branch you are currently located on (so make sure all of your changes are committed before running this). If you are not confident you did this correctly, you may want to go to a new directory (not in your repo) and run git clone --branch lab1_submission <repo_url> to clone your tag and verify that it builds and runs correctly.

If, after you create this tag, you want to change it (ie, re-submit your code), you can re-run the above commands and include the –force option to overwrite the tag, ie:

git tag --force lab1_submission
git push --force origin lab1_submission

For later labs, update the tag name appropriately:

lab1_submission
lab2_submission
lab3_submission
lab4_submission
lab5_submission
lab6_submission
lab7_submission
lab8_submission
lab9_submission
lab10_submission
lab11_submission
lab12_submission

If you don’t type the tag name correctly, it won’t count as submitted.



Last Modified: 2022-05-31 12:23:24 -0500