GitHub

—A How-To—

By Nick Kim


Why GitHub?

We want to pool our skills and efforts to create a working program. If we work separately, we end up with diverging code, and eventually we have to merge a pile of different versions of the same code and come up with something that works.

How will Git help? Git simplifies the complex task of tracking distributed versions of code. It will note and publish all deltas between your code and the version everyone else is playing with. That way we're all on the same page.

GitHub is an online service that acts as a centralized access point for various Git-tracked projects. As a simple analogy, Git is the notebook where you keep track of changes in your code. You take your notebook to every Tuesday meeting to communicate your ideas and what changes you've made. In this analogy, GitHub is the meeting room.


When GitHub?


How GitHub?

I've compiled instructions from several sources to bring you a step-by-step guide on setting up GitHub on your machine. Feel free to refer to the official Mac, Windows, or Linux guide; the official guides are probably more clear in certain areas.

Before we begin, note:

P({Things that should happen} ≠ {Things that will happen}) = 1

In other words, things will go wrong almost surely.

Contact me if you ever feel that these instructions have failed you.

There are two instances of this guide: the command line version and the graphical user interface (GUI) version (GUI not available for Linux).


The Command Line Guide

Setting Up GitHub

  1. Visit the GitHub site and create an account.
  2. Install Git on your computer.
  3. Open Terminal (on an OS X/Linux system) or Git Bash (on a Windows system).
  4. cd into the directory you wish to work in.
  5. Type: git config --global user.name [username] (without the quotes, and replace [username] by your GitHub username).
  6. Type: git config --global user.email [your e-mail address]
  7. Type: git clone https://github.com/username/projectname.git. This will create a folder called "projectname" in whatever directory you're in. You can replace the URL with the one from the GitHub page of the project you would like to contribute to.
  8. Log in with your GitHub username and password.

You can now start working on the program from within the folder you've just created.


Pushing Changes

  1. Make sure you've saved all of your files.
  2. If you've added any new files, type: git add [file]; e.g., git add testfile.txt.
  3. Type: git commit -a -m [comments]. Replace [comments] by a descriptive and useful summary of what you've changed. For example, if I fixed the error on line 1417, I would write: git commit -a -m "Fixed an error on line 1417, only five hundred errors to go!". Excitement is optional.
  4. Type: git push origin master.
  5. Log in.
  6. Your code is now in the central repository!

Revisiting the Code

Every time you decide to work on the code again, you should look at the project page and note any changes that have been made by others. Someone may have already fixed the section you were planning to work on.

Once you have reviewed any changes, go to the command line and type:
git pull https://github.com/kimolas/cmu-census-bmprogram.git. This will incorporate all of the changes made by others into your outdated local files.

Now that you have the latest files, you can start working! Follow the steps above (in the section "Pushing Changes") to commit and push your work back to the GitHub repository.

Return to the top of the page


The GUI Guide

Setting Up GitHub

  1. Visit the GitHub site and create an account.
  2. Install the GitHub application on your Mac or PC.
  3. Run the GitHub application.
  4. Log in if it asks you to, and specify a convenient location on your computer for your project folder.

Pushing Changes

  1. Make sure you've saved all of your files.
  2. Open the GitHub App.
  3. If you are using a Mac, open the "Changes" tab. It is located in the left sidebar.
    If you are using a PC, double-click the project "cmu-census-bmprogram".
  4. You'll be presented with an overview of the changes you've made.
  5. Include a concise summary of your changes in the "Commit summary" field.
  6. Press "Commit & Sync".
  7. You've successfully pushed your changes to the central GitHub repository!

Revisiting the Code

Every time you decide to work on the code again, you should look at the project's page and note any changes that have been made by others. Someone may have already fixed the section you were planning to work on.

Once you have reviewed any changes, open the GitHub app and sync all changes (⌘+S on the Mac, Ctrl+S on Windows). This will incorporate all of the changes made by others into your outdated local files.

Now that you have the latest files, you can start working! Follow the steps above (in the section "Pushing Changes") to commit and push your work back to the GitHub repository.

Return to the top of the page


Updated 3 April 2015