Introduction to GitHub

I've been using people's code from GitHub for a couple of years and without it, I'd be totally stuck in my various projects. I want to give back.

I had a mixture of confusion and laziness around how GitHub works, which got in my way. I eventually figured it out, but it took some bumping around.

This Instructable will explain the basics of creating a Git repository, how it works and how to upload it onto GitHub.

I'll be using the commands from the Terminal application on the Mac, but the principles can be extended to other platforms as well.

What is Git vs. GitHub?
Git is a source code version control system, which a series of "commits" or snapshots of your code. You make the commits manually.

GitHub is a website (github.com) where you can publish your Git repositories for public download and possible collaboration.

First, you'll want to register for a GitHub account. You can create as many repositories you want, as long as they are public. Anyone can download your public link and use your code and contribute to the archive. I usually don't upload a repository (a.k.a. a "repo") unless I'm at a good point with the code and ready to make it public.

The sample code I'm using here is called lenenbot, which is a Twitterbot that mixes John Lennon with Vladimir Lenin quotes. It takes the first half of one and mixes it with the second half of another.

Specific Steps on the GitHub site
Log in
Go to the Repositories tab
Click on the green New button, which will bring up this dialog
Enter a name for your source code repository
Select the Public radio button
Enter a 1-sentence description
Check the Initialize the repository with a ReadMe file
Choose the green Create Repository button

Now, you have an new repository. A default README.md file will be displayed in GitHub

The easiest way to install Git on the Mac is to run a graphics package Installer. The latest installer is on Source Forge (note: the URL may change over time): http://sourceforge.net/projects/git-osx-installer/

Now, launch Terminal, where you will do the rest of the configuration. You will be configuring Git to upload your source code onto GitHub.

Note that Terminal uses the Bash shell, which essentially takes the same commands as a Linux installation on a Raspberry Pi.

The first thing you'll need to do is to specify your username and email. These should match the ones on your GitHub account. In the Terminal window, type in:

git config --global user.name "username"

my "username" is scottkildall. Please don't use this one. The username public  — my GitHub repositoties are at: https://github.com/scottkildall — yours will be on your GitHub URL path. To specify your email, which remains private, enter your email like here:

git config --global user.email "your_email@example.com"

 

 

In the Terminal window, type in a change directory command, such as:

cd /Users/<username>/<codedirectory>

username is your local username. codedirectory is the rest of your path. For this example, it is:

cd /Users/scottkildall/PythonScripts/lenenbot

An easy shortcut is to type go to the Finder and drag your folder onto the Terminal. This drag-n-drop shortcut will fill in the full directory path for you. 

cd stands for change directory. And for those wanting a cheat sheet of Unix/Linux commands, here is one that is pretty handy.

If you type in: ls then you will see a list of all the files in your directory, which helps to verify that you're in the right place.

In the Terminal window, type in:

git init

This will create hidden files that Git uses to manage its source code control. The idea is that you will have a single local directory which you will sync with the one on your GitHub account.

If you delete or replace the contents of this directory, it will mess up your configuration, so try to avoid anything like this.

You only need to do this once for each Git repo on your local drive.

In this case, a "pull" request means that you are downloading files from GitHub into your local directory and a "push" request means that you are uploading files from your local directory onto GitHub

In the terminal, type in:

git remote add origin https://github.com/<username>/<repo name>.git

where <username> is your GitHub account username and <repo name> is your repository name that you just created.

In the case of lenenbot, this would be:

git remote add origin https://github.com/scottkildall/lenenbot.git

To communicate with the outside world, Git uses remotes. These are repositories other than the one on your local disk which you can push your changes into (so that other people can see them) or pull from (so that you can get changes from others). This is essentially how this system works for Git and GitHub.

The command git remote add origin creates a new remote called origin located on GitHub.

Once you do this, you can push to origin instead of typing out the whole URL.

Now, type in:

git pull origin master

This command will download the contents of your newly-created repository into your local directory. In this case, it is just the README.md file.

Note: You can have your source files in your current directory, the download won't replace existing files (except for an existing README.md file).

The .md stands for markdown and is the same kind of text-editing marking format that Wikipedia uses.

Rather than editing it by hand, I use an application like Mou to edit the README.md file.

Describe what your source code does: a summary for someone looking at it for the first time.

In Terminal, enter:

git add .

This will add all the files (and recursive directories) to what will be a new "commit" of your source code.

Note, this command won't echo any response in the Terminal window.

Now, you need to commit the files that you've just added, creating the snapshot of your source code.

Type in:

git commit -m "initial source commit"

The -m flag is used to add a message about your the commit, which is standard practice. This should be a description of the most recent changes you've made.

You'll see some details, which shows which files were included in the commit.

Pushing the code will upload your local changes to the github repo.

Type in:

git push origin master

This will upload your local repository into the remote connection that we previously called origin and master is the branch name (we don't cover branching in this Instructable).

That's the short guide. Please don't ask me about branches and the more thorny details, but this should get your started.

You can repeat steps 7-9 whenever you make a change.

The full documentation is here, which is worth reading as you find Git/GitHub to be more and more useful.

And if you want to follow @lenenbot on Twitter, here is the account page.