Computer Science

Introduction to GitHub

It's great to be able to use git on your local machine for managing a complex project, but its real strength is in allowing you to interact with other people. A git server might be run by an organization to allow team members to share work on a project, and for the rest of us, there's GitHub.

Table of Contents

  1. What is GitHub
  2. Downloading a Repository
  3. Using git with GitHub for project management
  4. Signing Up for GitHub
  5. Cloning a repository for which you are a contributor
  6. Cloning a repository and issuing a pull request
  7. Creating your own GitHub repository for a project
  8. Moving a previous project up to GitHub

0. What is GitHub?

Some people choose to host their own distribution system for software projects. John Gruber's Markdown project is available as a zip file from https://daringfireball.net/projects/markdown/ , for example. You have also downloaded code for this class from our course server or the course website.

GitHub, at https://github.com, is an online service that allows for public (or private) hosting and sharing of source code.

If you're only using git to manage your own code on your local machine, you don't really need GitHub. But if you're interested in posting/sharing your code with the world (as a service, or as a Computer Science resumé), using code that others have written, or even contributing to other people's projects, GitHub is the de facto standard tool for that.

For our purposes we're going to discuss four ways that you can interact with the GitHub website.

1. Downloading a repository

Because much of the material on GitHub is publicly accessible and open source, it is easy to download a project to your local computer. This is one way of accessing code on GitHub, and certainly the easiest. When you find a project, click on the green "Clone or download" button and select "Download ZIP". A zip file of the project will download onto your computer, and you can open it up and begin trying it out, experimenting with it, or using it as you wish.

You should understand that this code may have issues, may have bugs, may not work on your computer, and may potentially be harmful to your computer. GitHub isn't known for having malware, but anytime you execute unknown code on your computer, you should be careful. One of the advantages to GitHub is that the code is visible to users, so you have the ability to inspect people's work for issues.

Download a repository

A repository is just a project. Let's try downloading a project to see what we get.

Go to https://github.com/fivethirtyeight/data, click on the green "Code" button, and select "Download ZIP to download a compressed zip file of that project. What you'll receive in your Downloads folder is a 63.2 Mb file that contains data used by the website fivethirtyeight.com as research for some of their stories. There is data on the Avengers movie, on "airline-safety," on "nfl-wide-recievers," and on "classic-rock." Assuming this material is licensed for your use (check the LICENSE file—it is!), you can use it in your own projects as needed.

Downloading (or cloning) a repository means that you have a complete, standalone copy of that project on your computer that you can examine, run, and use. Sometimes that's just what you want, but sometimes you may want to use git and GitHub in a more powerful way.

2. Using git with GitHub for project management

We're going to go through the process of signing up for a free GitHub account, and then we'll get some practice in using GitHub in a few different ways.

This is about to be awesome

Not everybody gets to learn computer science in high school, and taking this course already opens the doors to a whole new series of experiences for you.

If you go into a computer science or software engineering field, the fact that you're learning about GitHub is even better. The more you know about version control, the more desirable you are as a prospective intern or employee.

College students use GitHub to manage their projects. Some Poly students do as well. You may even end up using your GitHub repository as a type of resumé. This is the real deal. Pay attention!

3. Signing up for GitHub

3.1. Get a GitHub account

Sign up

Go to GitHub.com and click on "Sign up" to create an account. You'll need to enter a username, an email address (perhaps your school email—you can change this later) and a (good) password. Follow the instructions to create a Free Plan.

Give some thought to making a good username. If you have a "handle" that you use for social media accounts that might be useful here... as long as it's an appropriate username.

Once you've got your GitHub handle, share that userID with the instructor.

3.2. Get your Personal Access Token

A Personal Access Token (PAT) from GitHub is used to make your account even more secure, and is used when you interact with GitHub on the command line (Terminal).

Get a Personal Access Token for GitHub

  1. Sign in to your GitHub account.
  2. Click on your user icon in the upper-right corner of the screen and select "Settings."
  3. On the left-side menu click on "Developer Settings."
  4. Select "Personal Access Tokens" on the left-side menu. You can name the token if you wish, and set the expiration for the token to some value. Click on the repo box to set the Scope for this token. (If you don't do this, you'll have a token that doesn't let you do anything, and you'll get 403 errors when you try to work on your repositories.)
  5. See the PAT that has been generated for you and copy it down someplace on your computer where you can use it to authenticate on the command line when needed. If you lose this access token you can always log back in to GitHub and generate a new one.

3.3. Two ways to collaborate on a project with a group

There are primarily two ways that you can contribute to a project when you're working with a team of people.

1. Pre-approved collaborator

One way to contribute to a project is to become a collaborator on that project. With your username, the project developer or maintainer can add you to the list of collaborators on the project.

With this strategy you will:

  1. Clone the project from GitHub onto your computer
  2. Fetch the most recent version of the project
  3. Make changes to the project, including
    • git add .
    • git commit -m "message"
  4. Push your changes to the project.

You might use this strategy if you're part of a lab team working on a project together, or if your teacher invites you to participate in a group project.

2. Volunteer Contributor

If you are not a pre-identified collaborator on a project, you may still be able to contribute. In this strategy you:

  1. Fork the project from somebody's GitHub account to your own GitHub account
  2. Clone the project from your GitHub onto your computer
  3. Make changes to the project, including
    • git add .
    • git commit -m "message"
  4. Push your commit to your fork on GitHub.
  5. On your GitHub account, submit a pull request to the project maintainers, asking them to consider pulling your changes into the project.

You might do this if you find a project that is interesting to you, and you decide you want to provide support in some way: writing code, fixing code, writing documentation, etc.

 

We'll try out both of these processes.

4. Cloning a repository for which you are a contributor

(Contributing to your own project)

Recall that in our local use of git on our computer, we initialized git with a project by moving into the project directory and issuing the command git init. When you're working with a git-based project hosted at GitHub, instead of initializing the project, you clone the project from the GitHub server.

  1. Find the project you are going to contribute to
    For our first GitHub based assignment in here, locate the HelloWorld project hosted at https://github.com/rwhite5279/HelloWorld.
  2. Clone the project onto your computer
    Click on the green "Code" button, and under the Clone section, with HTTPS selected, copy the indicated URL to your clipboard.
    Now, in a Terminal on your computer, navigate to a folder where you typically do your development. I'll use this as an example here: 
    % cd ~/Desktop/compsci_projects/
    Now, use the git clone command to make a local git repository for that project. 
    % git clone https://github.com/rwhite5279/HelloWorld.git
    If you do an ls -a command now, you'll see that there is a .git directory in your folder. You now have a copy of someone else's project on your computer, and one that you can work on and contribute to. The clone process allows your local repository to remember the connection to the remote repository.

4.1. Working on the project

The process of working on this remote repository project proceeds just as it would with a local repository project: you'll make edits in the working directory, add those changes to a virtual staging area, and when you've completed a step of some significance, commit those changes to your project.

  1. In your local repository that you've just cloned, in the StudentDirectories folder, create a new folder with the name lastnamefirstinitial . Within this new folder place an additional text file called helloitsme.txt . The contents of that text file can be whatever you wish.
  2. Using the usual git commands, add the directory to your local repository (for staging), and commit your changes locally.
    1. git status
    2. git add .
    3. git commit -m "message"
    4. git log
  3. You've committed the changes locally, but the project located on the server won't know about any of this until you push your version back up to the project. Remember that when we cloned this project git established a connection to the server that it remembers. In the project directory, type git push to send your update version of the project to the directory.
    rwhite@MotteRouge$ git push Counting objects: 3, done. Delta compression using up to 4 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 288 bytes | 288.00 KiB/s, done. Total 3 (delta 2), reused 0 (delta 0) remote: Resolving deltas: 100% (2/2), completed with 2 local objects. To https://github.com/rwhite5279/HelloWorld.git 42393c4..e3204cd main -> main

My push didn't work!

If there has been a recent update to "main" version of the repository at GitHub, git won't allow a push of the update until any differences (conflicts) have been resolved.

If you're lucky, no one else has made any edits that conflict with yours. You can resolve the situation by using git pull to get a new, updated version of the repository, and then issuing your git push.

If there have been changes on the main repository that that do conflict with your edits, you'll have to resolve the resulting merge conflict.

5. Forking a GitHub repository, cloning it to your local machine, and issuing a pull request

(Contributing to someone else's project)

In the previous "clone-push" process you were able to push to the project directly because the "project maintainer" (your instructor) had added you as an official collaborator. It's possible that in the process of pushing your version of the project up to GitHub, there could be a merge conflict that needed to be managed. That's a normal part of the process when you have multiple people working on the same project.

It's also possible for you to contribute to a project for which you are not an invited collaborator.

Let's see how this works.

Forking, cloning, and pull requests

  1. Log in to GitHub, go to https://github.com/rwhite5279/ForkMe , and click on the "Fork" button in the upper right corner of the screen. You will be asked to identify which account you should fork it to. Select your own GitHub account.
  2. You now have a copy of that project, separate from the owners, associated with your GitHub account. This fork is a fully operational project with a git history of its own, but this one "belongs" to you. From GitHub, you can clone it to your computer (just like you did the project above), make your own changes to it on your local machine, make your own commits to it on your local machine, and push those commits back up to GitHub where your fork of the project will be modified.
  3. Go ahead and do that: Clone this new project to your computer (see above for instructions), modify the project by adding a folder with your studentID as its name, and with a file helloitsme.txt in it. Then add that modification to the project, commit it, and push it up to your GitHub repository for that project.
  4. Although you have made changes to your fork of this project, those changes won't be reflected in the original version owned by the project admin: you're not a project collaborator and thus don't have permission to modify the project that way. What you can do, if you think you've actually contributed something that the project admins will find useful, is submit a pull request to the administrator of the original project, who will be notified that someone has made some modifications to the project that might be considered for inclusion there.

    On GitHub, after you've pushed up the modification from your own machine, click on the "Pull Request" button. The admin will be notified that you have submitted a modification, and deal with it accordingly.

When people talk about contributing to open source projects, this process of forking the project, modifying it, and submitting a pull request is how it happens. Once you're familiar with this process, contributing to Open Source might not seem so scary.

6. Creating your own GitHub repository for a project

Even if you don't contribute to someone else's open source project, you might have the need to post your own open source project on GitHub. This is a great way to share what you've done with others (who can download your work as needed), or to create an off-site backup of an important project.

GitHub free accounts are not private!

Before you consider uploading a project to GitHub, understand that it will publicly available to The World, unless you are paying for the option of creating a private repository. That may be to your advantage (if you're trying to show people the fine work you've done), and that could be to your disadvantage if your project accidentally has a file in it called "my_secret_passwords.txt."

This is not a joke. This actually happens. Be careful.

6.a. A new repository started at GitHub site

To create a new, empty repository for a project that you are about to start:

  1. Sign in to your GitHub page.
  2. Click on the Repositories tab and then on the green "New" button on the right.
  3. Follow the instructions to fill out the information for the new repository. You should probably create a README file, as recommended.
  4. Once the GitHub repository has been created, clone the repository to a suitable location on your computer. From here on out you'll be able to develop the project and push your commits up to GitHub as you wish.

Read on to see how you can put a non-git project that you've already got on your computer up on GitHub.

6b. Moving a previous project up to GitHub

If you're new to GitHub you may find that you have a project on your computer that you've already started (or already completed), and you didn't start with the project on GitHub. You may not even have used git with this project, but you want to put it up on your GitHub account, probably because you want to share your work with your instructor, your classmates, collaborators, or others.

As an example, we'll use a project I've been working on lately, a Mandlebrot plotter.

  1. Make sure the project is contained in a directory with the project name. In this case, my project folder is called Mandelbrot.
  2. Make sure you have at least a minimal README.md file in the directory.
  3. Create an initial commit of your project using the standard steps:
    1. git init if you haven't yet set up git tracking with this project
    2. git add . to add all the files into your staging area
    3. git status to check the status of your project before committing
    4. git commit -m "First commit" to make your first commit of the project.
  4. Log in to your GitHub account, click on the Repositories tab, and then click on the green New button.
  5. Give the repository the same name as the directory on your computer with the project name. For my project, it's Mandelbrot. Leave the "Initialize this repository with a README" box unchecked. This will allow you to push up your existing repository in a moment.
  6. On the next page you'll see different strategies for initializing this project on GitHub, including this one:
    "...or push an existing repository from the command line"
    $ git remote add origin https://github.com/rwhite5279/Mandelbrot.git $ git branch -M main $ git push -u origin main
    Let's go ahead a do that...
  7. On your computer, cd to your project's directory...
    $ cd Mandelbrot
    and then type the first line given:
    $ git remote add origin https://github.com/rwhite5279/Mandelbrot.git
    This establishes a link between your project and the online GitHub repository. Now establish the branch that you're working on as the main:
    $ git branch -M main
    Now push your existing project (which you've already committed locally) to the server using the second line given in the instructions:
    $ git push -u origin main
    From here on out you can work on your project locally as usual, and just do a normal git push when you're ready to upload a commit to the server.