CS0500 Github Guide

We use GitHub and git to give you access to project code, to allow you to save your work online so you can access it from anywhere, and to facilitate collaboration on partnered work. In CS500, we will be expecting you to access git through the terminal/command line and through GitHub. GitHub does have a companion app, but we do not recommend you use it and will not be able to support you in making it function.

What is GitHub?

GitHub is a code-hosting platform that is used by many programmers to save their code and access it from any machine. Think of it like “the cloud” but for code projects! This guide is your go-to resource for help with GitHub/git setup as well as git commands you should know in order to interact with GitHub from your local machine.

Making an Account

First, you’re going to need a GitHub account which will be an invaluable resource to you for the rest of your computer science career (both at Brown and beyond). To create an account:

1. Go to www.github.com
2. Select “Sign up” in the upper right corner
3. Follow the steps on the website to get your account all set up :)

Installing Git

Thankfully, installing git on your computer is super easy! First, we need check if you already have git installed on your computer. To do this, we’ll need to use a terminal, which is how you’ll primarily interact with git. If you haven’t used a terminal much before, that’s okay! You’ll gradually learn more in this course and others, starting now!

To open a terminal and check if git is installed:

1. First, open the terminal on your computer:

   1. On Mac: Go to Applications > Utilities > open Terminal

      • (Alternatively, you can open Spotlight Search (keyboard shortcut is “Command+Space’’), search for “terminal”, and open the first application listed)

   2. On Windows:  Open the Search bar,  enter “command prompt”, and click the first application listed

2. Enter the command git --version and press Enter

If you already have git installed, your terminal should print the version you have (the version you have shouldn’t matter, as long as you have it installed). You can ignore the rest of this section.

If get some error like “command not found”, you need to install git. To do this, expand the instructions below:

Configuring git settings

Next, we need to to connect git on your computer to your GitHub account. To do this:

1. In your terminal, enter the command git config --global user.email "<email>", where <email> is replaced with the email you used to make your GitHub account (don’t forget the quotes!).

2. Enter the command git config --global user.name "<name>" where <name> is replaced with your username (don’t forget the quotes!).

When you enter each command, you shouldn’t see anything print in your terminal—this is expected. Git is configuring itself behind the scenes! (Often, terminal programs don’t print anything when they run successfully—many only print a message when something goes wrong.)

Documentation tip: A common convention for software (which we will follow in CS500) is to write commands like this:

some_command_here <parameter>

The <angle brackets> indicate that parameter is a placeholder for you to fill in—the documentation will tell you what to put there. When you fill in the placeholder, don’t include the angle brackets—they are just notation to tell you it’s a placeholder when reading. So, if you were supposed to write “cabbage” for parameter, you’d type in:

some_command_here cabbage

Keep this in mind as you read this and other documentation!

Creating your Github access token

When you use git to connect to Github, you need to provide credentials to Github to prove you are the user you claim to be. To do this, you can create a Personal Access Token—this is similar to a password, but more commonly used when a program (eg. git) is logging in on your behalf (rather than asking you to type a password).

Note: If you had a GitHub account before, you may have used a password-based authentication. This is no longer supported, so you also need to follow the steps below!

To create your github Personal Access Token, do the following:

1. Open your github profile settings.

2. In the page that opens, scroll down to the very bottom left and click on Developer Settings, which looks like this:

3. In the Developer Settings page, look at the sidebar on the left and click on Personal Access Tokens > Tokens (classic), like in the red box below:

4. After clicking on Token (classic), you should see the following screen. Click on Generate new token > Generate new token (classic). Be sure to pick the classic token!

5. Then, you should see a window that looks like the image below. Make sure to fill in all of the following options as shown in the image:

• Name: This is the name of your token—you can name it whatever you want (eg. “cs500”).
• Expiration: Select “No expiration”. You can ignore the warning from Github.
• Select scopes: Select the “repo option. This will check several other boxes under “repo”.

7. Take a moment to double-check that you have filled in all the settings as on the figure, then click Generate Token.

After you generate your token, you should see a page like this:

9. Your token is a super-secret value like a password—you’ll enter it when closing repositories. Copy this token and save it somewhere safe you can access it later.

10. One final step: we can configure git to remember your token the first time you clone a repo (you’ll do this later), that way you hopefully won’t need to enter it more than once. To do this, enter the following in your terminal:

git config --global credential.helper store

Once again, this command won’t produce any output.

Great job! You should be all set for authenticating your Github account for this class. Now you’re ready to clone repositories!

If you’re reading this guide for the first time, take a look at the terminology in the next section, then go back to continue with your IDE setup. You’ll use git again to before you start running code!

Git terminology

Before you start using git, here is some important GitHub terminology you should familiarize yourself with:

• Repository → a GitHub repository – or repo for short – is what a project on GitHub is called. Each time you accept an assignment for CS0500 by clicking on the assignment link, GitHub will create a repository for you for that project.
• Commit → The cool thing about GitHub is that it can keep track of all of the versions of your project as you edit them. Each project “version” is called a commit. It is basically a snapshot of your project at a moment in time, and it is up to you to create commits when you reach points in your project that you do not want to lose. (Your project will be saved on your local machine, but in order to save a snapshot on your GitHub, you must create a commit and push it to your GitHub). It is good practice to create commits regularly so if something gets messed up while you are coding, you will have old versions to look back at stored on your GitHub repository.

The next few sections describe some common tasks you’ll do using git—the other course documentation will tell you when you need these, but remember that they’re here in case you need them.

More git resources

For more info about git, we recommend checking out the following links:

• Git - The Simple Guide: a quick and dirty introduction
• Harvard CS61 intro to git: a nice pictoral reference
• Git handbook: an in-depth introduction

Common git tasks

This section outlines some common tasks for working with git. As you work on other assignments, we’ll refer you to these sections as you need them:

• How to clone a git repository?: you’ll do this once for every project
• How to push your code to Github?: you can do this to save your work on Github, and to collaborate with others on the partner projects
• How to create a Personal Authentication Token?: you’ve already done this, but look here if you need to create another token

Cloning a git repository

Cloning a repository is how you download code to your computer. Depending on the assignment, there are two ways we might give you code to run, which changes how you will clone it:

• For Homework/Project/Lab stencils, we will give you a Github Classroom link (eg. https://classroom.github.com/<something>).  To use these, see Accepting Github Classroom Assignments
• For HW, lecture code, or other examples, we will directly provide a direct Github Repository URL (eg. https://github.com/<something>).  To use these, see Cloning from a Repository URL.

Accepting an Assignment on GitHub Classroom

Github Classroom links allow us to set up a unique repository to hold your code for an assignment or project.  To use it:

1. Accept the assignment on GitHub Classroom by following the link on the handout and clicking the “Accept this assignment” green button.

2. Github will now create your repo–wait a few seconds and refresh the page.   When it’s done, you should see a link to your shiny new Github repository (like the example below), click this link to view it!  

This link will open the main view of your repository on Github.  Next, we need to download (or clone, in git terms) the repository to our system:  to do this, see the next section.  

Cloning a repository by URL

Once we have a link to a repository, you can download it to your computer by “cloning” the repository into your CS500 folder with git.  To do this:

1. If you have not done so already, open the repository link in your browser.  
2. On the Github page, click the green “Code” button and click the copy button to copy the link.

Getting to your CS500 folder

To clone the repo, we’ll need to use the terminal to browse to your CS500 folder and run git to download the code.  If you’re new with using a terminal, that’s okay!  Follow the steps below for a step-by-step guide.  Even if you’re more comfortable using a terminal, skim all of these instructions to make sure you understand the process–you might learn some useful shortcuts!

1. First, open the terminal on your computer:

   1. On Mac: Go to Applications > Utilities > open Terminal

      • (Alternatively, you can open Spotlight Search (keyboard shortcut is “Command+Space’’), search for “terminal”, and open the first application listed)

   2. On Windows:  Open the Search bar,  enter “command prompt”, and click the first application listed

Quick intro to terminals

Just like when you browse folders in a window on your computer, in a terminal, there’s a concept of a current “working directory”, which is the folder where the terminal is “looking” at one time.  The working directory is usually displayed in the terminal’s prompt, which is the line where you enter commands. 

To see the current working directory, enter the command pwd, like this:

Here, the working directory is the user deemer’s Desktop folder. 

Another way to write this is ~/Desktop, where ~ is shorthand for a user’s home folder.  

2. Next, we need to navigate to our CS500 folder in the terminal.  There a few ways to do this—use whichever you feel most comfortable:

Cloning the repository with git

Next, you can download the repository to your computer–in git, this is called “cloning” the repository.  To do this:

1. Enter the following command using the link you copied from Github. 
   git clone <pasted link> (without the “<>” brackets)

2. If you are prompted to log in, enter the following:

• Username: Enter your Github username (not your Brown username)
• Password: Paste in your Github Personal Access Token (eg. ghp_XXXX...). If you don’t have one, see these instructions. (Note: you won’t see the password in the terminal as you paste/type it—this is normal, just paste and press enter.)

After you log in successfully, you should see output something like this:

  Cloning into '<name of repository>'...
  remote: Enumerating objects: 39, done.
  remote: Counting objects: 100% (39/39), done.
  remote: Compressing objects: 100% (33/33), done.
  remote: Total 39 (delta 8), reused 37 (delta 6), pack-reused 0
  Receiving objects: 100% (39/39), 372.97 KiB | 6.32 MiB/s, done.
  Resolving deltas: 100% (8/8), done.

2. If your output looks like this, your repository was cloned successfully, yay! If you see an error saying Forbidden or Access denied, make sure you are using the Github Access Token you created

Once you have cloned the repository, you should now see a folder in your CS500 with the same name as the repository you cloned.  This is where the code lives!

To continue working with the code, you’ll need to open the repository in an environment such as VSCode.

How do I push my code to Github?

If you want more information on what the actual commands do, then go to the Need to Know Commands section that goes through the commands needed to git push. However, here is a step-by-step guide with pictures that allows you to push your code to Github.

1. After you have made some changes, navigate to your terminal at the bottom of IntelliJ/VSCode. Additionally, make sure that you are in the same directory as your project/homework/lab.

2. Next, type in the following command: git add . (make sure that there is a space between the add and the period). There should be no output after.

3. Next type in the following command: git commit -m "message" where the particular message is the message for your git commit. For example, since I edited my AttributeNode class in my Decision Tree project, I can type in the following commit message. Additionally, you can see the files that you have changed, the insertions that you made, and the deletions that you have made in the commit log.

4. Next type in your git push command.

Appendix: Helpful git commands

If you have any git problems, feel free to post on Ed!

Please let us know if you find any mistakes, inconsistencies, or confusing language in this or any other CSCI0500 document by filling out the [anonymous feedback form].