Cyrus Stoller home about consulting

Github for Non-Techies

I was having a discussion with a friend from college who needed to have some “minor” changes made to her website. She had originally paid a web developer to make it, but was frustrated with how long it was taking him to make changes and she was on a tight deadline. She asked if I would be willing to help her out. I told her that I couldn’t commit to being her full time web developer, but that I’d be willing to take a look at the code if she put it on Github. I said that I’d be willing to make a pull request if she told me exactly what she needed changed.

That’s when I realized that we were bound for a train wreck. She had never taken any computer science classes and had never opened the Terminal on her Macbook. In her words:

terminal : me :: elevator : claustrophobe

So, since I was going to write this up for her anyway, here’s my explanation of how to get Github setup and how to create a repository. To me, the instructions on the Github website are really clear and direct, but they’re targeting an audience that has used the Terminal before and may have an opinion in the emacs vs vim debate (go emacs!).

The first question my friend asked me, was “where do I type?” I think most geeks just take this starting point for granted. So, here’s my attempt at a literal step-by-step tutorial.


Opening the Terminal on a Mac

Open /Applications/Utilities/Terminal.app. For those of you don’t know what this means. Go to your Applications folder, then scroll to the bottom and open the Utilities folder. In there you’ll see a lot of really useful applications that Apple provides. Open Terminal.

Hopefully you can see how /Applications/Utilities/Terminal.app translates to opening the Terminal. This is called a path.

Great job. Now breathe. The blinking cursor is your friend. I promise.

Basic UNIX commands

I have a cursor. Great … I could have just opened Microsoft Word or TextEdit and seen something similar.

Except, those prompts would not have let you take complete control of your computer. Don’t worry, you won’t be able to do anything too harmful without getting a warming or being prompted for your password.

Notation of the prompt (aka Command Line)

When describing what to type into the Terminal many people will prepend each command with $ or >. You don’t need to type the character that is denoting the prompt, which is often referred to as the Command Line. For example, if you see:

$ cd ~/Documents/
$ pwd

You would type cd ~/Documents/ and then press return, then when you get the next prompt, you would type pwd and then press return. Always be sure to type exactly what was written. For the most part, the Terminal prompt or Command Line, is case-sensitive.

Basic File Navigation

I’m hoping that you don’t save all of your files on your desktop like my dad does. Most people make folders or in UNIX parlance directories.

When you first launch the Terminal you will start in your home directory, which is notated at ~ in shorthand. This is the folder that has your Desktop, Documents and Downloads folders. You can use this shorthand at the Command Line. For example:

Practice Changing Directories

$ cd Documents

You are now in your Documents directory. You can verify this with $ pwd, which will output something like /Users/cyrusstoller/Documents. To go back to your home directory you have a few options:

  1. $ cd ~ will change your working directory to your home directory.
  2. $ cd .. will change to you working directory’s parent directory, in other words the folder that your current working directory is in. In this case that happens to be your home directory.

“Ok. Great. I can use $ pwd to see which directory I’m in, but how do I see which directories I can go into?” Type $ ls to see all of the files in your current working directory. (If you try to cd into a file that isn’t a directory you’ll get an error.)

Try to cd into a bunch of your directories. Use ls to see what is in each directory. And type pwd to confirm that you are where you think you should be.

Now use $ mkdir my_new_directory to create a new directory (or folder) called my_new_directory in your current working directory. You can cd into it and see that there is nothing inside. If you just type $ cd you will go back to you home directory. To go into my_new_directory you type $ cd my_new_directory.

These are just some of the very basics in UNIX file navigation. Here are some other resources that you may want to check out, if you’re feeling confused, or are eager to learn more tricks.

Setting up your Github account

This is the easy part. Go to github.com and create an account. Unless you need to keep your code private, a free account should do just fine. You’re going to follow the instructions that the good folks at Github have written up.

Creating your first repository

Great job setting up your account. Now let’s create a repository by following these instructions.

Here are the highlights and why they’re important.

$ cd ~/Documents/
$ mkdir Github
$ cd Github
$ mkdir <SAME AS YOUR REPOSITORY NAME>

More or less everything that you put in this folder will be put on Github. As you get more advanced you’ll learn why you might not want everything to go to Github (ie Database passwords etc …) - to prevent certain files from getting uploaded you can read more about .gitignore files here. While you can technically make the name of your directory different than the name of your repository it will just make your life a lot more difficult.

Here’s where my friend got lost. What is a text editor? Do I just type into Microsoft Word? For the most part, the answer is no.

Adding files that already exist somewhere else

In my friend’s case she had some PHP files that her web developer had emailed to her (this seems really sketchy, but I’m just going with what I’ve been told). For her she could just drag and drop those files into her new git repository. To quickly open here current directory so that she could drag and drop like she’s used, use $ open . - the . refers to your current directory. You should hopefully see your newly created empty folder. Now drag and drop your files into this folder.

Creating new files with a text editor

You can skip this section if you already dragged files into your git repository.

On the Github help page they mention $ touch README - that just creates a blank file called README. Github treats files named README in a special way. If you’ve ever gone to a Github and see some instructions at the bottom or an explanation of what the repository is, that text comes from the README file. If you want to learn more read here.

You can also use emacs, vim, TextMate, Komodo, TextWrangler, etc … to create new files in your repository. Yes, you can also have directories inside of your repository; git will recursively look through everything in your directory where you initialized your repository.

Making your first commit

Even though your files reside in the same folder as your repository, they haven’t actually been added to your repository yet. You need to make a commit. Git is a version control system. You can think of each commit being a “version” of the files in your repository that you want to keep track of. I would recommend being generous with your commits. In other words, commit often. Git is smart. It only save the differences between each commit so you’re not going to “wasting” a lot of space on your hard drive.

Ok. So how do I make a commit?

At a very basic level there are two steps to creating your first commit: 1. staging what you want in your commit 2. finalizing your commit.

  1. You use $ git add . to add everything in your current directory to your “staging area”. (Remember the . notation from earlier?) As you learn more, you can add files individually. And as you get more advanced, you can add only parts of a file. But, I digress…
    • You can try $ git status to see what has been added to your staging area. It will say Initial commit above your files. That’s just indicating that your git repository doesn’t have any commits yet.
  2. You use $ git commit -m "My initial commit" to finalize your commit and add it to you git repository. The -m tells the commit command that you’re going to be passing a message along with your commit. It’s good form to always make a note of what you were changing in each commit. In this case our message was "My initial commit".

Here’s a blog post that explains the concept of “staging” in more depth.

Excellent work. Now type $ git log to see a list of all of your commits. You should see one message. At this point, you have created your first git repository and created your first commit. Well done. But, you haven’t put your repository on Github yet. It’s just on your local machine.

If you type $ git status you can see if any files have been modified since your last commit.

Putting your first repository on Github

Now that you have a git repository on your computer, how do you put it on Github.

If this your first time creating a repository Github might provide instructions on how to do this. You can follow the instructions that are on your repository page. And skip to the next section.

  1. Go to the your github repository in your favorite browser (ie Safari, Chrome, Firefox, etc ..): https://github.com/<your github username>/<your github repository name>/
  2. There copy a string that looks like git@github.com:<your github username>/<your github repository name>.git by clicking the clipboard icon next to it.
  3. Go back to your terminal and make sure that you’re still in the same working directory as your git repository.
  4. $ git remote add origin git@github.com:<your github username>/<your github repository name>.git This connects your local git repository to the repository that you have on Github.
  5. $ git push origin master This tells git to push the commits on your master branch to the origin repository, which is your repository on Github.

No reload you repository page on the Github website and you should see your files there. Congratulations.

Adding new commits

Great work. You have your first commit on Github. w00t.

To add new files. You can drag and drop them into the folder that contains your git repository. Then do the following once you have navigated to your git repository using cd:

$ git add .
$ git commit -m "<message for what you did>"

Git is smart and tracks files that you have already added and will show you changes that have been made. You’ll see the differences by using the $ git diff command. You should see the changes that you just made. Type the letter q to exit.

If you just want to see which files have been modified use the $ git status command. It will show you a list of the files that have been modified.

To undo, use $ git checkout . to restore the state of the last commit. This will erase any changes you have made since your last commit. To confirm that, try $ git status and it should say “Nothing to commit.”

Additional Resources

I hope this is helpful. Good luck and happy coding.

Category Tutorial