Introduction: 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.

Step 1: Create a Repository on the GitHub Site

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

Step 2: Install Git

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"
 

 

Step 3: Go to Your Source Code Directory

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.

Step 4: Initialize Git

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.

Step 5: Pull the ReadMe.md File From Your GitHib URL

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).

Step 6: Edit the 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.

Step 7: Add Your Local Git Files

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.

Step 8: Commit the Add

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.

Step 9: Push the Code to the Github

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).

Step 10: Done, Repeat 7-9 As Needed

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.

Comments

author
SteveG3 made it!(author)2014-10-10

great tutorial, just used it to copy files from my raspberry pi

author
DCengineer made it!(author)2014-03-13

Well done basic tutorial... However, it is worth noting to viewers that Git does not require GitHub or even a server, and can be used locally. It would be a good idea to eventually explain some of the more powerful capabilities of Git such as interactive staging, branches, tags, .gitignore, merging, rebasing, resetting, and stashing.

There is a good book that I read that can be found on git-scm.com called Pro Git. I wanted to set up a server, so I read the whole thing (around 300 pages), but the first 3 chapters will give a you a basic understanding.

Also, in terms of a GUI tool, I have found that 2 in particular seem to work well.

Mac and Linux - Git Cola

Windows - Git Extensions

Note that Git Extensions will give you the option to install Git and a tool called KDiff3. I cannot say anything about the included Git installation due to the fact that I just installed it using the default installer from the git-scm website. I would not suggest installing KDiff3. Although it is very powerful, I have had issues with it - it seems that it doesn't like to apply the last change.

However, I have recently discovered a tool called Meld available for Mac, Windows, and Linux that provides a much nicer (if less powerful) interface. I would suggest using that for merging.

Summary:

Good Instructable.

Go to git-scm.com, find the Git Pro book, read it.

If you are on Linux or Mac install Git-Cola and Meld.

If you are on Windows install Git Extensions and Meld.

Hopefully you find these tools and resources as useful as I do.

author
scottkildall made it!(author)2014-03-14

Thanks for taking us to the next stage.

Indeed! There's a lot more out there. And most importantly, as you point out, Git runs separately from GitHub.

I'll look into these features you've suggested — a lot are beyond my current skills.

author
DCengineer made it!(author)2014-03-13

One more consideration: look into Mercurial (also referred to as hg). It is far simpler than Git but less powerful. Just note that it is less common than Git, so sometimes you may run into compatibility problems. However, tools exist (specifically git-hg and hg-git) that allow you to work with other repos through your SCM tool of choice.

For those who don't know:

SCM = Source Code Management

CVS = Central Versioning System

SVN = Subversion (a common CVS tool)

DVCS = Distributed Version Control System (Git and Hg are examples of this, and have many benefits over CVS-based systems)

Git does not stand for anything. Its name is a self-insulting remark by Linus Torvalds (the creator of Git and Linux).

About This Instructable

28,842views

56favorites

License:

Bio: Scott Kildall is an new media artist and researcher. He works at Autodesk, Pier 9 and is an artist-in-residence with the SETI Institute
More by scottkildall:Pier 9 Guide: Fusion 360 to OMAX WaterjetStrewn Fields: Waterjet Etching Into StonePier 9 Resource: Setting up 2D profiles for CNC in Fusion 360
Add instructable to: