If you've found yourself on this page, we're assuming you're brand new to Git and GitHub. This guide will walk you through the basics and explain a little bit about how everything works along the way.
Download and Install Git
At the heart of GitHub is an open source version control system (VCS) called Git*. Created by the same dudes that created Linux, Git is responsible for everything GitHub related that happens locally on your computer.
*If you don't already know what Git is, take a crash course.
Download and install the latest version of Git.
Good to know: Git won't add an icon anywhere, it's not that sort of application.
Set Up Git
Now that you have Git installed, it's time to configure your settings. To do this you need to open an app called Terminal.
Username
First you need to tell git your name, so that it can properly label the commits you make.
git config --global user.name "Your Name Here"# Sets the default name for git to use when you commit
Git saves your email address into the commits you make. We use the email address to associate your commits with your GitHub account.
git config --global user.email "your_email@youremail.com"# Sets the default email for git to use when you commit
Your email address for Git should be the same one associated with your GitHub account. If it is not, see this guide for help adding additional emails to your GitHub account. If you want to keep your email address hidden, this guide may be useful to you.
Password caching
The last option we need to set will tell git that you don't want to type your username and password every time you talk to a remote server.
Good to know: You need git 1.7.10 or newer to use the credential helper
To use this option, you need to turn on the credential helper so that git will save your password in memory for some time:
git config --global credential.helper cache# Set git to use the credential memory cache
By default git will cache your password for 15 minutes. You can change this if you like.
git config --global credential.helper 'cache --timeout=3600'# Set the cache to timeout after 1 hour (setting is in seconds)
Good to know: The credential helper only works when you clone an HTTPS repo URL. If you use the SSH repo URL instead, SSH keys are used for authentication. This guide offers help generating and using an SSH key pair.
Celebrate
Congratulations, you now have Git and GitHub all set up! What do you want to do next?
Generating SSH Keys
If you have decided not to use the recommended HTTPS method, we can use SSH keys to establish a secure connection between your computer and GitHub. The steps below will walk you through generating an SSH key and then adding the public key to your GitHub account.
Step 1: Check for SSH keys
Have an existing keypair you'd like to use? You can skip to Step 4.
First, we need to check for existing ssh keys on your computer. Open up Terminal and run:
cd ~/.ssh# Checks to see if there is a directory named ".ssh" in your user directory
If it says "No such file or directory" skip to step 3. Otherwise continue to step 2.
Step 2: Backup and remove existing SSH keys
Since there is already an SSH directory you'll want to back the old one up and remove it:
ls# Lists all the subdirectories in the current directory # config id_rsa id_rsa.pub known_hosts mkdir key_backup# Makes a subdirectory called "key_backup" in the current directory cp id_rsa* key_backup# Copies the id_rsa keypair into key_backup rm id_rsa*# Deletes the id_rsa keypair
Step 3: Generate a new SSH key
To generate a new SSH key, enter the code below. We want the default settings so when asked to enter a file in which to save the key, just press enter.
ssh-keygen -t rsa -C "your_email@youremail.com"# Creates a new ssh key using the provided email # Generating public/private rsa key pair. # Enter file in which to save the key (/home/you/.ssh/id_rsa):
Now you need to enter a passphrase.
# Enter passphrase (empty for no passphrase): [Type a passphrase] # Enter same passphrase again: [Type passphrase again]
Which should give you something like this:
# Your identification has been saved in /home/you/.ssh/id_rsa. # Your public key has been saved in /home/you/.ssh/id_rsa.pub. # The key fingerprint is: # 01:0f:f4:3b:ca:85:d6:17:a1:7d:f0:68:9d:f0:a2:db your_email@youremail.com
Step 4: Add your SSH key to GitHub
Run the following code to copy the key to your clipboard.
sudo apt-get install xclip# Downloads and installs xclip xclip -sel clip < ~/.ssh/id_rsa.pub# Copies the contents of the id_rsa.pub file to your clipboard
Be warned: it is important to copy the key exactly without adding newlines or whitespace. Thankfully the
xclip
command makes it easy to perform this setup perfectly.
-
Go to your Account Settings
-
Click "SSH Keys" in the left sidebar
-
Click "Add SSH key"
-
Paste your key into the "Key" field
-
Click "Add key"
- Confirm the action by entering your GitHub password
Step 5: Test everything out
To make sure everything is working you'll now SSH to GitHub. When you do this, you will be asked to authenticate this action using your password, which for this purpose is the passphrase you created earlier. Don't change the git@github.com
part. That's supposed to be there.
ssh -T git@github.com# Attempts to ssh to github
You may see this warning:
# The authenticity of host 'github.com (207.97.227.239)' can't be established. # RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48. # Are you sure you want to continue connecting (yes/no)?
Don't worry, this is supposed to happen. Verify that the fingerprint matches the one here and type "yes".
# Hi username! You've successfully authenticated, but GitHub does not # provide shell access.
If that username is correct, you've successfully set up your SSH key. Don't worry about the shell access thing, you don't want that anyway.
If you see "access denied" please consider using HTTPS instead of SSH. If you need SSH start atthese instructions for diagnosing the issue.
Create A Repo
If you've found yourself on this page, we're assuming you're brand new to Git and GitHub. This guide will walk you through the basics and explain a little bit about how everything works along the way.
Make a new repo on GitHub
Every time you make a commit with Git, it is stored in a repository (a.k.a. "repo"). To put your project up on GitHub, you'll need to have a GitHub repository for it to live in.
Click New Repository.
Fill out the information on this page. When you're done, click "Create Repository."
Congratulations! You have successfully created your first repo!
Create a README for your repo.
While a README isn't a required part of a GitHub repo, it is a very good idea to have one. READMEs are a great place to describe your project or add some documentation such as how to install or use your project. You might want to include contact information - if your project becomes popular people will want to help you out.
Step 1: Create the README file
In the prompt, type the following code:
mkdir ~/Hello-World# Creates a directory for your project called "Hello-World" in your user directory cd ~/Hello-World# Changes the current working directory to your newly created directory git init# Sets up the necessary Git files # Initialized empty Git repository in /Users/you/Hello-World/.git/ touch README# Creates a file called "README" in your Hello-World directory
Open the new README file found in your Hello-World directory in a text editor and add the text "Hello World!" When you are finished, save and close the file.
Step 2: Commit your README
Now that you have your README set up, it's time to commit it. A commit is essentially a snapshot of all the files in your project at a particular point in time. In the prompt, type the following code:
git add README# Stages your README file, adding it to the list of files to be committed git commit -m 'first commit'# Commits your files, adding the message "first commit"
Step 3: Push your commit
So far everything you've done has been in your local repository, meaning you still haven't done anything on GitHub yet. To connect your local repository to your GitHub account, you will need to set a remote for your repo and push your commits to it:
git remote add origin https://github.com/username/Hello-World.git# Creates a remote named "origin" pointing at your GitHub repo git push origin master# Sends your commits in the "master" branch to GitHub
Now if you look at your repository on GitHub, you will see your README has been added to it.
Celebrate
Congratulations! You have now created a repository on GitHub, created a README, committed it, and pushed it to GitHub. What do you want to do next?
Fork A Repo
If you've found yourself on this page, we're assuming you're brand new to Git and GitHub. This guide will walk you through the basics and explain a little bit about how everything works along the way.
Contributing to a project
At some point you may find yourself wanting to contribute to someone else's project, or would like to use someone's project as the starting point for your own. This is known as "forking." For this tutorial, we'll be using the Spoon-Knife project.
Step 1: Fork the "Spoon-Knife" repo
To fork this project, click the "Fork" button.
Step 2: Clone your fork
You've successfully forked the Spoon-Knife repo, but so far it only exists on GitHub. To be able to work on the project, you will need to clone it to your local machine.
Run the following code:
git clone https://github.com/username/Spoon-Knife.git# Clones your fork of the repo into the current directory in terminal
Step 3: Configure remotes
When a repo is cloned, it has a default remote called origin
that points to your fork on GitHub, not the original repo it was forked from. To keep track of the original repo, you need to add another remote named upstream
:
cd Spoon-Knife# Changes the active directory in the prompt to the newly cloned "Spoon-Knife" directory git remote add upstream https://github.com/octocat/Spoon-Knife.git# Assigns the original repo to a remote called "upstream" git fetch upstream# Pulls in changes not present in your local repository, without modifying your files
More Things You Can Do
You've successfully forked a repo, but get a load of these other cool things you can do:
Push commits
Once you've made some commits to a forked repo and want to push it to your forked project, you do it the same way you would with a regular repo:
git push origin master# Pushes commits to your remote repo stored on GitHub
Pull in upstream changes
If the original repo you forked your project from gets updated, you can add those updates to your fork by running the following code:
git fetch upstream# Fetches any new changes from the original repo git merge upstream/master# Merges any changes fetched into your working files
Create branches
Branching allows you to build new features or test out ideas without putting your main project at risk. In git, branch is a sort of bookmark that references the last commit made in the branch. This makes branches very small and easy to work with.
Pull requests
If you are hoping to contribute back to the original fork, you can send the original author a pull request.
Unwatch the main repo
When you fork a particularly popular repo, you may find yourself with a lot of unwanted updates about it. To unsubscribe from updates to the main repo, click the "Unwatch" button on the main repo.
Delete your fork
At some point you may decide that you want to delete your fork. To delete a fork, just follow the same steps as you would to delete a regular repo.