CS200 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 CS200, 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:

Go to www.github.com
Select “Sign up” in the upper right corner
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:

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
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 and skip to Configuring git.

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

Instructions for MacOS (click to expand)

In your terminal, enter the command xcode-select --install
This will download a set of recommended development tools from Apple, including git. If you want to install git another way, look here.
Follow the prompts to finish the installation. The process may take several minutes.
Verify you have Git installed by running git --version in your terminal again. You may need to quit and reopen your terminal for this to work.

Instructions for Windows (click to expand)

Go to this page. This should prompt an automatic download of git, but if not, click the link to manually download git.
Open the .exe file you downloaded and click next through each of the installation pages–there is no need to adjust any settings, all the defaults are fine.
Verify you have Git installed by running git --version in your command prompt again. You might need to quit and reopen your the command prompt window for this to work.

Configuring git settings

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

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!).
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 CS200) 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:

Open your github profile settings by clicking on your profile icon in the top-right. Then, click Settings, like this:

In the page that opens, scroll down to the very bottom left and click on Developer Settings, which looks like this:
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:

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!

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. “cs200”).
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”.

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:

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

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 (eg. HW0), take a look at the terminology in the next section, then go back to HW0 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 CS0200 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 an Assignment on GitHub Classroom
For HW0, 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:

Accept the assignment on GitHub Classroom by following the link on the handout and clicking the “Accept this assignment” green button, which should look like this:

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 CS200 folder with git. To do this:

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

Getting to your CS200 folder

To clone the repo, we’ll need to use the terminal to browse to your CS200 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!

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.

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

Shortcut method (Mac)

Outside your terminal, open up your CS200 folder in Finder (the standard file/folder browser on Mac)
Drag the Finder window onto the Terminal icon on your dock (like the figure below). This should open a terminal already pointing to your CS200 folder! Pretty awesome, right?? 😎
(If this doesn’t work for you, just go with the classic method.)

Shortcut method (Windows)

Outside your terminal, open up your CS200 folder the way you’d normally search for a file
Inside the folder, hold down Shift and Right Click in the blank area in the folder view
In the menu that opens, click “Open PowerShell window here”. (PowerShell is another terminal program inside Windows, similar to command prompt.)

If this method doesn’t work for you, just try the Classic method.

Classic Method

In your terminal, use the cd command to enter into your CS200 folder. The command for this will depend on where your CS200 folder is located on your computer–here’s what it should look like based on the folder locations we’ve recommended, but you can adjust it if you picked a different spot:

Mac (CS200 folder on Desktop): cd ~/Desktop/CS200 or
cd "/Users/your-name-on-mac-here/Desktop/CS200"
Windows (CS200 folder on C: drive): cd C:\CS200

For more information on using terminal commands, take a look at our Terminal Guide, which describes cd and other commands in more detail.

At this stage, you should now have a terminal open to your CS200 directory! Now we can finally clone the repository.

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:

Enter the following command using the link you copied from Github.
git clone <pasted link> (without the “<>” brackets)
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.

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 CS200 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–see the stencil setup guides for the language you’ll be using:

For Java code, look here for instructions on opening your code in IntelliJ
For Python code, look here for instructions on opening your code in VSCode and setting up your environment

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.

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.

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.

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.

Next type in your git push command. If you see the output below, then you have successfully pushed your code to Github.

If you want to check that your code got pushed, then click on the blue link that is highlighted below:

If you click on that link, that will take you to your Github repository and you will see your commit message on the files that you have changed.

Appendix: Helpful git commands


Command	Explanation
`git clone <repo URL>`	Once you accept an assignment and your repo is created, click the green “Code” button and copy the link that is listed. That link is your repo URL. Then, in your terminal, type this command with the repo URL to make a folder with the code in your repo on your computer. The folder will be made in whichever directory you are currently in, so be sure to cd into your desired directory before running this command!
`git add <file>` OR `git add -A`	This command is the first of 3 commands that you need to run when you are trying to get the code you wrote on your computer back up to GitHub. You must add the files that you want to update on GitHub. You can do this by running git add with one file specified at a time, or you can use `git add -A` to update all files (typically what is used when you want to save a snapshot of your current code).
`git commit -m “<message>”`	Once you have added all of the desired files using git add, you are ready to commit these changes and save your snapshot to GitHub! This command is the 2nd of 3 commands you must run to get your code edits back up to GitHub. It creates the commit, or “snapshot” that we will soon send to GitHub. Instead of `<message>`, you should write something informative about what you’ve changed!
`git push`	Now you’re ready to push the changes to GitHub! Running this command will send your commit to the online repository where your code is stored. This is the final of the 3 commands you will run to get your code back to GitHub! After running this, go on your GitHub repo and ensure that your updates were made!
`git pull`	This command lets you pull any changes on this repository that are present on GitHub but not on your local machine. No need to worry about this for solo projects, but if you’re working on partner projects, pull before you begin working / after you commit and before you push in order to get all your partner’s changes!

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

Dealing With Merge Conflicts

This section of the guide is adapted from CS15’s debugging lab <3

When working with a partner and using GitHub, you may run into merge conflicts while updating the same file. For example, when one partner runs git pull to get the most up-to-date version of the code, they may encounter an error message like this:

(base) katieli@Katies-MacBook-Pro-1333 katieli1 % git pull
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint: 
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint: 
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.

If this happens, run git config pull.rebase false to attempt a merge. After you do this, you may get an error in your terminal that says you have a merge conflict.

Merge conflicts generally arise when two people have changed the same lines in a file, or if one person deleted a file while another was modifying it. It’s important to know how to resolve these conflicts so you can continue to code and work. Your code will not compile and run if you have merge conflicts. You can easily see the files that have merge conflicts since IntelliJ will highlight them in a different color and put squiggly read lines under the file names.

You’ll notice some strange characters on the file:

<<<<<<< HEAD
    [the code Partner B wrote]
=======
    [the code Partner A wrote]
>>>>>>> 48ceadf56648d2736a68f88bde2d16390c4e6f87 (or some other long string)

Think of these as conflict markers. The code after <<<<<<< HEAD are changes that you made (HEAD represents the current commit you’re working on). The ======= line acts as a divider. The code below this line and the >>>>>>> [commit hash] line are changes being brought in (that your partner made!), in this case from a different git commit 48ceadf56648d2736a68f88bde2d16390c4e6f87. This long number is the commit hash. Think of it as a unique ID for each commit made on the repository.

In order to resolve this conflict and have your code successfully compile, you should remove all of the lines in the conflict marker EXCEPT the lines that do what both you and your partner want. The first thing that we should do is communicate with our partner about which parts of the code we want to keep. Once we decide that, we can remove everything else. For example, if you decide that you want to keep Partner B’s code, you can remove Partner A’s code and all the conflict markers. Then, once only Partner B’s code remains, you can commit and push the result to Github.

How Can We Avoid Merge Conflicts?

Here are some guidelines for reducing the number of merge conflicts you encounter.

Run git pull before you start modifying any code during your partner projects. This will get your local code up-to-date with the repository on GitHub before you start coding, thus avoiding the chance that you modify something locally that your partner has also changed – the basic cause of a merge conflict.
Add, commit, and push your code to GitHub as soon as you finish working on your project for a period of time. Make sure that your local code is always pushed to GitHub as soon as you’ve made any changes – even if it’s just two lines. This is so that your partner can pull those changes when they start working, and the code on both of your computers will match each other.
Commit any changes you have before pulling. Git won’t let you pull changes from the remote if you have changes in your code that you haven’t committed.
Communicate! Communication with your partner is key to reducing the number of merge conflicts you encounter.

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