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.
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.
I have a cursor. Great … I could have just opened
Microsoft Word
orTextEdit
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.
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.
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
.
$ cd filename
is analogous to opening a directory (file) called filename
.
It’s short for change directory. $ pwd
will show you where you are. It’s
short for print working directory.$ ls
lists everything in your current working directory$ mkdir foo
creates a new directory called foo
in your working directory.
It’s short for make directory.$ man <commandname>
and it will show you the man
or
manual
page for that command. Whenever I have something like
<commandname>
supplement that with something else. For example try $ man
pwd
to see the man page for the pwd
command. If you want to close the man
page type the letter q
.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:
$ 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 home
directory.$ 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.
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.
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.
Github
in 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 $ pwd
you 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
cyrusstoller
.$ git init
You 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 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.
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 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.$ 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.
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>/
git@github.com:<your github
username>/<your github repository name>.git
by clicking the clipboard icon
next to it.$ 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.$ 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.
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.”
I hope this is helpful. Good luck and happy coding.