Here are the step by step instructions to getting rolling with Git and contributing on GitHub.
Note on command samples
Lines beginning with
$ are commands that you type. The
$ just represents your command prompt, yours may differ (oftentimes the command prompt shows the current user and what directory they're in). Lines lacking a
$ are generally the output of commands; they're information or results that the commands are giving you.
What is Git? What is GitHub?
Git is an open source version control software. Think of it as a way to manage multiple people working on the same project; Git allows them to smartly "merge" changes to avoid conflicts. It also keeps a history of the project, so that you can roll back to a time before an error was introduced.
GitHub is a cloud-based storage site for git. It is a central place where everyone can download projects, track ongoing issues, and view information. It's not the only such site—Gitorious is another one, for example—but it's very popular and has some nice features.
First Step - Install Git
See Pro Git Chapter 1.4 Getting Started.
On Windows: Visit git-scm.com and click the download button for Windows. Once installed, you should have a Git Bash app as well as a contextual option to "Open Git Bash here" whenever you right-click on a folder in Windows Explorer. Git Bash responds to the same commands as Terminal apps on Mac or Linux so you'll be able to use the same commands despite using a different platform.
Install XCode.app, a free (but humongous) download in the Mac App Store. Run XCode and go to Preferences > Downloads > Components and then Install the Command Line Tools.
Alternatively, use the graphical Git installer.
Or, if you have Homebrew installed, run
brew install git.
On Debian-based Linux (including Ubuntu), open a Terminal app and type
sudo apt-get install git. You will be prompted for your password and Git will be installed.
On Fedora Linux, open a Terminal app and type
sudo yum install git-core. You will be prompted for your password and Git will be installed.
Not sure if Git is installed? In a terminal, type
which git. If Git is installed and available, it will print out a path to where Git is installed, e.g.
$ which git /usr/local/bin/git
Pretty sure Git is installed, but
which git is still returning nothing?
It's possible that Git is installed but is not in your path. In order to get Git in your path, you need to add a command like
to the .bash_profile file in your home directory (create a .bash_profile if none exists). This
export command essentially says "prepend the path to Git to my PATH environment variable" and it has the effect of making the Git command available in your Terminal.
Second Step - Create a GitHub account
This is one of the easier steps - just visit Github and register a username, pick a password, etc. Now we just need to tell Git our name and email. In a Terminal, run these commands:
$ git config --global user.name "Firstname Lastname" $ git config --global user.email "firstname.lastname@example.org"
There is a seven-minute video on YouTube that goes through the rest of the steps. While it gives a visual walk-through, it will probably be necessary to read the step-by-step directions below to figure out the how and why of it all.
Third Step - "Fork" and "clone" this repository
Up at the top of this repository's GitHub page, click the "Fork" button. An exact copy of the project will be added to our GitHub account. Now all we need to do is clone the project from GitHub onto your computer. Open up a Terminal and type
$ git clone https://github.com/YourUsername/Codeyear-IG-Github-Project.git
We'll see a result like this:
Cloning into 'Codeyear-IG-Github-Project'... remote: Counting objects: 70, done. remote: Compressing objects: 100% (59/59), done. remote: Total 70 (delta 34), reused 47 (delta 11) Unpacking objects: 100% (70/70), done.
Now, inside the Codeyear-IG-Github-Project folder, we have all the files of this project on your computer. Not only that, because this is a cloned Git repository, we have the entire history of the project. Try moving into the project's directory with
cd Codeyear-IG-Github-Project and running
git log to see the last few things that changed in the repository. Typing the letter
q will exit
Fourth Step - Add your name to the "List of People"
In the "Getting Started" folder is a list of people. For practice, open up the "List of People.mdown" file and add your name. It doesn't have to be your real name, though your GitHub account will be associated with your changes eventually. Now save the file and run the
git status command. We should see something like this:
# On branch master # Changes not staged for commit: # (use "git add <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: List of People.mdown # no changes added to commit (use "git add" and/or "git commit -a")
Understanding the idea behind a "commit" and our local changes is a major part of version control. Essentially, Git can tell that the file has been altered, but it has yet to add your changes to its history of the project. We can go crazy and edit files all we want, including potentially breaking the project we're working on, but should try to only commit a finished, working product because commits end up in the final history.
When we're done with our edits, the
git add command is where we stage our changes; we might edit one file, add it, edit another file, add it, and so on before actually running
git commit. The commit command finalizes our changes and adds them to the project's history. Let's walk through this whole process, running
git status throughout to see how things change.
$ git add List\ of\ People.mdown $ git status # On branch instructions # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: readme.mdown # $ git commit -m "Adding my name" [master c43ae4d] Adding my name 1 file changed, 1 insertion(+) $ git status # On branch master nothing to commit, working directory clean
We've used the
commit command in here, specifically
git commit -m. The
-m is a "flag" or option and in this case it stands for "message," so we're not only committing something to Git's history of the project but we're attaching the message "Add my name" to our commit. It is always a good idea to add a message explaining your changes. Many commands have multiple flags which can be very useful but
-m is the only one we'll need for now.
With but a handful of commands we've gone from having a perfect clone of the original project, to some changes that are not recorded by Git, to letting Git know which files we're going to add to its history, to adding those changes to the history, and then ending with a confirmation that the "working directory [is] clean" meaning that the last commit Git knows about and the current state of our files is identical.
We just made a
commit! Sweet! If we're still skeptical, we can run
git log which prints out the last several commits. Ours will be at the top.
$ git log commit ca82a6dff817ec66f44342007202690a93763949 Author: Awesome Sauce <email@example.com> Date: Mon Feb 18 22:30:15 2013 -0500 Adding my name
You can exit
git log by pressing the letter "q."
We actually still need to do one more thing; our changes are in Git's history, but only the Git history on our computer. If we visit github.com/OurUsername/Codeyear-IG-Github-Project it still won't have our name on the List of People. We need to
push our changes to the remote repository on GitHub. Luckily, this is a fairly simple command:
$ git push Counting objects: 11, done. Delta compression using up to 4 threads. Compressing objects: 100% (8/8), done. Writing objects: 100% (8/8), 2.65 KiB, done. Total 8 (delta 2), reused 0 (delta 0) To https://github.com/OurUsername/Codeyear-IG-Github-Project.git 07449e6..4257ccf master -> master
Now try visiting github.com/OurUsername/Codeyear-IG-Github-Project and browsing to the List of People; our name is on it! We've changed a file, added it to our local Git repository, and then pushed our local changes to the Git repository sitting in GitHub's cloud. This alone is pretty phenomenal; we now know how to publish our work online with a complete history included.
Digression on Escaping Spaces
We have to type
List\ of\ People.mdown instead of
List of People.mdown because spaces are meaningful characters on the command line; they separate one command from the next. The \ escapes the character that follows it. We can also wrap a string in quotes to escape it. But the biggest savior here can be tab completion; start typing "List" and then hit tab; suddenly, the rest of the file's name appears, escaped spaces and all. This can save us a lot of typing and help reduce mistakes.
Fifth Step - Send a Pull Request to add your changes
Up until now, we've been doing a whole lot of Git with very little "Hub." We used the Fork button to copy the project, sure, but we're just playing by ourselves and not contributing back to the original Codeyear-IG-GitHub-Project.
We've changed our local repository, and pushed those local changes to the remote repository, but what about getting the changes from our remote into the Codeyear remote? Simple, we use GitHub's brilliant addition to version control, the Pull Request.
A "Pull Request" is one of the conceptually trickier things about GitHub. Obviously, we can't just let anyone contribute to any repository; someone could mess up our precious work! But we want to be able to review external contributions and "pull" in their changes. So when we send a Pull Request we're essentially saying "hey, you should pull these changes into the original project."
Every GitHub repo (we're cool enough to just call them repos by now) has a Pull Request button up at the top. GitHub has a nice help page that walks us through the process, which is basically:
- Go to your repo and click "Pull Request"
- Pick the Master branch—it's the only branch we have right now—and then select the corresponding Master branch of LibraryCodeYearIG/Codeyear-IG-Github-Project as the target to receive your changes
- Write a brief title and description for our edification
- Hit "Send pull request"
Someone from the Libcodeyear organization will review your pull request and accept it.
Sixth Step - View the project online & see your changes!
You just contributed to a project on GitHub, congratulations! Pretty cool, isn't it? Relax and get yourself a delicious beverage, you've earned it.
I'm addicted; where can I do more?
The Learning Git Resources document in this repository has links to a few more tutorials, some of which cover new features we didn't talk about. Check them out and report back if any are particularly good or bad!