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
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.
/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
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.
I have a cursor. Great … I could have just opened
TextEditand 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.
When describing what to type into the
Terminal many people will prepend each command with
>. 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.
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
$ cd filenameis analogous to opening a directory (file) called
filename. It’s short for change directory.
$ pwdwill show you where you are. It’s short for print working directory.
$ lslists everything in your current working directory
$ mkdir foocreates a new directory called
fooin your working directory. It’s short for make directory.
$ man <commandname>and it will show you the
manualpage for that command. Whenever I have something like
<commandname>supplement that with something else. For example try
$ man pwdto see the man page for the
pwdcommand. If you want to close the man page type the letter
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
Downloads folders. You can use this shorthand at the Command Line. For example:
$ 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:
$ cd ~will change your working directory to your
$ 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
“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.)
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.
$ 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.
This is the easy part. Go to https://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.
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.
Githubin your documents folder.
$ 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.
$ cd <SAME AS YOUR REPOSITORY NAME>if you type
$ pwdyou should see something like
/User/cyrusstolller/Documents/Github/<SAME AS YOUR REPOSITORY NAME>. Clearly, your file path won’t include your username (on your computer, which may be different from the one you setup on Github) instead of
$ git initYou need to initialize your git repository. Git doesn’t magically know which folders you want to treat as repositories, so here you’re telling git that this directory is “special.”
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.
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.
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
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.
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.
$ 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…
$ git statusto see what has been added to your staging area. It will say
Initial commitabove your files. That’s just indicating that your git repository doesn’t have any
$ git commit -m "My initial commit"to finalize your
commitand add it to you git repository. The
commitcommand 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.
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.
https://github.com/<your github username>/<your github repository name>/
email@example.com:<your github username>/<your github repository name>.gitby clicking the clipboard icon next to it.
$ git remote add origin firstname.lastname@example.org:<your github username>/<your github repository name>.gitThis connects your local git repository to the repository that you have on Github.
$ git push origin masterThis tells git to push the commits on your master branch to the
originrepository, which is your repository on Github.
No reload you repository page on the Github website and you should see your files there. Congratulations.
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
$ 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 your use the
$ git checkout . command. 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.”
I hope this is helpful. Good luck and happy coding.