Dear Lifehacker, I have learned to code and would like to start using GitHub to manage my projects. Despite the introductory lesson the site provides, I still don’t understand how it works. Can you help me? Sincerely, Git Help
GitHub can definitely be confusing for first-time users — even regulars trip up from time to time. GitHub knows it too, so it has created software (for Mac and Windows) to make the process a bit easier. Nevertheless, it’s good to learn the old-fashioned way, otherwise the options in the simplified software won’t make sense. Let’s start by walking through the basics.
Step 1: Sign Up for GitHub
Make yourself a GitHub account by signing up on the front page. After completing the form, GitHub will sign you in and take you to your empty news feed. In the middle of the page, you will see the boot camp (pictured to the right). We’re going to go through it to set up your account and create your first repository. Click on “Set Up Git” to get started.
Step 2: Install Git
GitHub is based around an old version control application called git. It runs via the command line and has no fancy graphical user interface. Since it’s made to manage code you wrote, this shouldn’t sound too scary. (Of course, as previously mentioned, GitHub did make wonderful software to allow you to use its service without the command line, but that won’t help you too much unless you know the basics.)
Git reads a local code repository — a folder containing code for your project — on your computer, and then it mirrors that code elsewhere (in this case, GitHub’s servers). Initially we will commit (send) your entire local repository to GitHub, but that’s just a one-time affair. As you continue to work on your code, you will simply commit changes. GitHub will then keep track of the changes you made, creating different versions of files so you can revert back to old ones if you want (or just keep track of those changes for other reasons).
This is primarily why you would want to use a version control system like git on your own, but additional benefits surface when using git to manage code with other people working on your project. When multiple developers commit code using git, GitHub becomes a central repository where all the code that everyone is working on can stay in sync. You will commit your changes, and other developers will “pull” or sync your changes to their respective local repositories. And you do the same with their code.
Git is what makes all of this happen, so you need to download the latest version and install it. On Mac, you just need to install the command line app. On Windows, you get a few more items. We will discuss how they work in the next step.
Step 3: Set Up Git
To set up git, you need to make your way into the command line. On Mac, that means launching the Terminal app (Hard Drive -> Applications -> Utilities -> Terminal), and on Windows that means launching the Git Bash app you just installed — not the Windows command prompt. When you’re ready, tell git your name like this:
git config --global user.name "Your Name Here"
For example, mine would look like this because I’m using a test account for this example:
git config --global user.name "Adam Dachis"
You can put in any name you like, but afterwards you’ll need to input your email and that email must be the email you used when signing up for GitHub:
git config --global user.email "email@example.com"
If, for whatever reason, you signed up for GitHub with the wrong email address, you will need to change it.
Now, to avoid always entering your login credentials and generating SSH keys, you want to install the credential helper so that your passwords are cached. If you are on Windows, download it and install it. If you’re on Mac, you will need to handle this through the Terminal. To start, use this command to download the credential helper:
curl -s -O http://github-media-downloads.s3.amazonaws.com/osx/git-credential-osxkeychain
This will download a small file and shouldn’t take too long. When finished, enter the following command to make sure the permissions are correct on the file you just download (and fix them if not):
chmod u+x git-credential-osxkeychain
Now it’s time to install the credential helper into the same folder where you install git. To do so, enter this command:
sudo mv git-credential-osxkeychain `dirname `which git``
You will be prompted for your administrator password, because the above command began with sudo. Sudo is shorthand for “super user do” and is necessary when performing a task that requires root access. The sudo command allows you to become the root user (a user with permission to do pretty much anything) on your operating system for a moment so you can perform this task. You are asked to enter your password to prove you are an administrator on the computer and should be allowed to do this. Once you have entered your password and the credential helper has been moved, finish up the installation with this command:
git config --global credential.helper osxkeychain
Now you are all set and can move on to actually using git and GitHub!
Step 4: Create Your First Repository
Now that you are set up, you can create a repository (or “repo” for short). Head on over to GitHub and click the “New Repository” button on the top right of your account page. (Note: If you are still displaying the GitHub bootcamp section, it will show up underneath it.)
When creating a repository, you have a few things to decide, including its name and whether it will be publicly accessible or not. Choosing a name should be simple, because you probably already have a name for your project. If you are just following along for learning purposes, use “Hello-World”. Why “Hello-World” and not “Hello World”? Because spaces and special characters will cause problems. Keep it simple and easy to type in the command line. If you want to include a more complex name, you can add it to the optional description field beneath the name field.
If you’re creating an open-source project, you want a public repository. If you want to code by yourself or share only with specific people, a private repository will do. Make the choice that works best for you and your project.
Before you click the “Create repository” button, check the “Initialize this repository with a README” checkbox. Why? All repositories require a README file. Ideally that file would contain a little information about your project, but you might not want to deal with that right now. By initialising the repository with a README, you will get an empty README file that you can just deal with later. For the purposes of this tutorial, we’re going to leave the box unchecked. In the next section, we are going to create a README file from scratch to practise committing (sending) it to GitHub.
Step 5: Make Your First Commit
When you send files to GitHub, you commit them. We are going practise by initialising your local repository and creating a README file to commit. Before you start, you need to know where your local code repository is on your computer and how to access it via the command line. In this tutorial, we are going to assume there is a directory called “Hello-World” in your computer’s home folder. If you need to create one, just run this command (same for Git Bash on Windows and OS X’s terminal):
Now change to that directory using the cd (change directory) command:
In case you were wondering, the ~ represents your home directory in Git Bash and Terminal. Now that your repository is ready, type this:
If you already had a repository ready to go, you would just need to
cd to that directory and then run the
git init command in there instead. Either way, your local repository is ready to go and you can start committing code. Don’t have anything to commit? Run this command to create a README file:
Let’s take a break for a second and see what just happened. Go into the home folder on your computer and look at the Hello-World folder (or look at whatever folder you are using for a local repository). You will notice a README file inside, thanks to the command you just ran. What you won’t see is a .git folder, but that’s because it’s invisible. Git hides it in there, but because you ran the
git init command, you know it exists. If you’re sceptical, just run the
ls command in Git Bash/Terminal to display a list of everything in the current directory (which, if you’re following along, is your local repository).
So how does git know we want to commit this README file we just created? It doesn’t, and you have to tell it. This command will do the trick:
git add README
If you want to add other files to commit, you will use the same command, but replace README with the name of a different file. Now, run this command to commit it:
git commit -m 'first commit'
While the other commands were pretty straightforward, the commit command has a little more going on, so let’s break it down. When you type
git, that’s just telling the command line that you want to use the git program. When you type
command, you’re telling git you want to use the commit command. Everything that follows those two thing count as options. The first, -m, is what’s known as a flag. A flag specifies that you want to do something special rather than just run the commit command. In this case, the
-m flag means “message”, and what follows it is your commit message (in the example, ‘first commit’). The message isn’t absolutely necessary (although you will usually need to provide one), but it acts as a reference to help you differentiate the various versions of a file (or files) you commit to your repository.
Your first commit should go by in a split second because you haven’t actually uploaded anything yet. To get this empty README file to GitHub, you need to push it with a couple of commands. Here’s the first:
git remote add origin https://github.com/yourusername/Hello-World.git
You need to replace “yourusername” with — you guessed it — your GitHub username. For me, it would look like this:
git remote add origin https://github.com/gittest1040/Hello-World.git
This command tells git where to send your Hello-World repository. Now all you need to do is send it:
git push origin master
Once you run that command, everything (in this case, just your README file) will make it’s way over to GitHub. Congratulations on your first commit!
Using GitHub requires more than just committing a README file, but these basics should give you a good grasp on how to interact with the git app and the service. Now that you know how GitHub works at its core, you can use the GitHub apps to manage your code.
Have fun managing your code!
Got your own question you want to put to Lifehacker? Send it using our contact tab on the right.