Demystifying Github: Simple tutorial so programming students can work together on projects

GitHub is an online service that’s helps people collaborate on projects when multiple files are being worked on by multiple people. If you and I are both working on tweaks to our company’s mission statement, what’s to prevent us from overwriting each other’s work? What if you make a really interesting change that I could learn from, but I don’t see it until you submit your final changes?

In the dark ages (the 90's), before the light of standardized version control that is GitHub, people constantly ignored and overwrote each other’s work. To avoid this, complicated filenames were used:

group_project_final_for_real_this_time_v_23.js

presentation_graphics_fixed.ppt

internal_newsletter_blue_border_added.docx

Before enrolling in Flatiron School, I tried self-teaching for a short period. “Why not ask for advice from my developer buddies who’re already working?”, I thought, “Shouldn’t I learn from people already working in the field?” For me, that wasn’t the best approach. I was overwhelmed by my friend’s suggestion, that I use I shiny software meant to simply Github for you, GitKraken. Underneath the glittery app, I had no idea what I was supposed to. To use GitKraken this early was like giving someone a Tesla before they can even see over the wheel.

I needed to keep it simple, and Flatiron School helped bring us up to speed. Luckily, Flatiron School walked us through the theory and practice.

A GitHub repository is a place to store Git files related to a program/application online, so that people can easily collaborate on them. It’s important not to conflate GitHub and Git. Git as a version control system predates GitHub, with GitHub being only one of many remote hosts that host Git-related files (alternatives being Gitlab, Bitbucket, or self-hosted solutions).

A GitHub repo includes a list of files and folders, and usually a readme file. Here’s an example gif of a GitHub repository for my first group project (a tongue and cheek command-line RPG about Flatiron School):

In order to collaborate with others and make this work, here is the basic principle(from a newbie’s perspective) of why you want to use GitHub:

Unlike the old way of having 17 different filenames tracking changes, the entire point of GitHub is to merge changes incrementally in a single location (a GitHub repository or ‘repo’), so that everyone is on the same page and compliment each other’s work instead of overwriting it

For a brand new project, here are simple steps on a Mac or Linux OS:

• Create your GitHub repo so that others are able to collaborate with you. Navigate to the ‘+’ icon at the top-right of the site, go to https://github.com/new/, or go to the newly released http://repo.new
• Name your repo, and if you want, add a description
• If you want the whole internet to be able to see your project, keep the default (Public) setting. If you want to keep it locked down, select Private
• Select ‘Initialize this repository with a README’, to update using Markdown later, to let people know why your app exists and how to use it.
• Now, you’ll want to clone the repository from GitHub, to your local machine:

Click the clipboard icon to copy this, select either SSH or HTTPS as needed.

• There are ways to do this using IDEs such as VS Code or Atom, but this guide will use the terminal so you’re always able to operate in a pinch! Open your terminal and navigate to a folder where you want to store this repository while working on it. Type
  git clone whatyoucopiedfromstep5here
• With your project synced up to your own machine. You can now create your own branch. Branches allow people to make changes without overwriting each other’s work by accident. In your terminal type git branch to check what branch you’re currently on, which should be master. Master means that anything changes you push will directly overwrite the main project files. That’s exactly what we want to avoid. Create your own branch by typing git branch whateverYouWannaNameTheBranchHere. Now, you need to ‘checkout’ the branch, which has you leave the Master and enter another. Type git checkout whateverYouNamedYourBranchand now you’re in!
• Once in your new branch, you can now add any files and code to get the project started. Once you’re ready to add your changes, you need to ‘stage’ them so that GitHub knows your going to be making some changes. Type git add .to stage any changes you’ve made in entire directory (the ‘.’ here means the entire current directory).
• Now that changes have been staged. It’s time to commit them along with a useful comment to let others know what you’ve down. Type git commit -m "commit message here" . For example: git commit -m "Yellow background changed to grey for better visibility." Down the line, these commit messages can be used for release notes on new versions of your application.
• With changes committed, you’ll now push them, with git push origin HEAD

Here’s a review of how the last few steps should look:

• Ok, so now you’ll need to access your repo from GitHub’s website and pull in the new changes from the branch you created. This allows you to review what’s being added, and in the case of merge conflicts (two people editing the same file), you can decide which changes you want to include and which you want to reject. On the website, look at the overview for your project and click on branches button (you should see at least 2 at this point).

• Click on “New pull request”. You’ll see the commit message you added!

• Click on “New pull request”. You’ll see the commit message you added!
• If there aren’t any conflicts, click Merge pull request and you’re good to go!
• For any brand new collaborates, all they need to do is clone your repo (described above) and get coding!
• BONUS: For anyone who has already been working on their own branch of the project without having, on their own local computer, these new changes that you officially merged into the master branch with the previous step, they might need to get these new files to their machine. This way, there will be potentially less conflicts later when their changes are added. To do this, while someone is on their own (now outdated) branch, they need to checkout back into the master, git branch checkout master, and git pull origin masterto pull down the changes on the GitHub repo onto their local machine. Now, they need to (just within their machine) merge their own branch with the new master changes. Checkout back into the personal branch, and type git rebase master. This allows them to get up to speed, resolve any merge conflicts, and when they’re ready they’ll be able to add, commit, and push their changes following the previous steps.

That’s it!

It’s not as scary as it sounds, and even helps solo developers track their versions and changes.

Have fun out there collaborating on projects with GitHub!