Github Tutorial

We are going to review the basics of github now that you've had a chance to use it so you can catch up on anything you've missed, then we will go more in depth on some of the features which might help you in your final project, especially related to coding with other people.

Contents

Useful Links

Basics

Cloning a repository
  1. Go to the repository page on github and copy the web address
  2. git clone <html>
Getting Code From a Repository
  1. git pull
Dealing With Code
  1. git add <file> tells github to track that file
    • git add -A adds all untracked files not in .gitignore
  2. git commit commits the added changes to your local git repository
    • This only effects your computer, it doesn't push anything to the github website
    • git commit -am simultaneously adds changes to previously tracked files and commits them (it will not add a new file)
  3. git push pushes your changes to github online

Adding a Collaborator

To add a collaborator, go to the repository on github (online), and click on the plus in the top right corner, click the option for "New Collaborator." Find your teammates by their email or github user name and add them. They will be able to clone your repository and push code to it, but the repository will not appear in their list of repositories. There will be a line on their main github page saying they have been added to your repository.

Merge Conflicts

GitHub "merges" files by matching up lines from each file, which allows it to merge files automatically as long as two people haven't edited the same line of code. When this happens, GitHub has two options, and it has no way of knowing which one is correct, so it tells you there is a merge conflict, and lets you decide which code to keep.

Merge conflicts look like this (in the file with the conflict):

<<<<<<< HEAD
    code here 
    #this is where your edits to the code will be
=======
    different code here 
    #this is where other people's edits to the same lines will be
>>>>>>> 083457078470583439

HEAD is your local changes, the equals signs are where it switches from your changes to the other changes, and the giant number is the name of the specific commit you are trying to merge with. To deal with this, just open the file and find the conflicts, then delete everything you don't want. Then just add, commit, and push your changes.

Using gitignore

Gitignores are wonderful things, they allow you to tell GitHub that you want it to ignore a file, or a whole bunch of files. This is useful if you need to have a large video in your git repository, but don't want to (or can't) upload it to GitHub, or if you have 500 .txt files storing data that someone else can get for themselves if they really want it.

Using a .gitignore is really easy, you just make a file named .gitignore in your repository, and type the name of any files you want to ignore. These file names use the same syntax as the command line, where * means anything can go here: for example adding *.txt to the .gitignore will make github ignore all files ending in .txt.

If you have already started tracking a file and don't want to anymore, you can use git rm --cached <file>. This removes git's history of that file.

Using README

If your repository has a file README.md, it will be displayed under the repository on github. This file is an excellent place to put documentation about running the code in the repository. It uses the markdown formatting language which is documented specifically for github here. This is the README file for this repository, if you open the raw text version of it, you can see an example of some of the markdown formatting.

Branches

Sometimes you want to try things out, but you don't know if they're going to work, and you don't want to break the things you already have. Or you and your partner are doing different things on the same code, and you don't want to keep dealing with merge conflicts every time you sit down to do work. This is what branches are for

Quick Overview

Branches allow you to make changes to code while preserving a copy of the original. master is the branch you have been using, and it is the branch which should always hold the original working code. When you are trying things that might break everything, you should make a branch, get your code working, then merge that branch back into master. Alternatively, if everything you try fails miserably, you can just delete that branch and go back to the old code.

Making a Branch
Switching Between Branches
Push and Pull Revisited

Pull Requests

You generally want to make sure all code on the master branch works, so rather than just trusting that anyone who pushes code to master knows what they're doing, it is good to use pull requests to allow other people in the project to check over the new code before incorporating it into master.

pull request merge conflicts

Reverting

Version control is one of the most powerful aspects of GitHub. This basically means there is an infinite undo button, in case you save broken code. This undo button is called reverting. There are a lot of different ways to revert code depending on where changes have been made. The link below does a good job of outlining all of the ways you can get back to old versions of your code. guide to reverting in GitHub

SSH Keys

So, you know how you have to type in your username and password every time you commit something to github? There's a nice way around that, called ssh keys. here is the beginning of GitHub's tutorial for setting them up. Once they're set up, you should clone repositories using the SSH URL, not the HTTPS URL, then you won't need a password.