The popular code-hosting website GitHub is a great resource for people looking to develop software in an open, collaborative environment. GitHub provides a way for other people to download, use, and ultimately contribute to your project, and gives you the added security of knowing that a copy of your project is stored on GitHub's external servers, so you won't lose all your work if your local machine fails.
Despite everything that GitHub has to offer, it's not the easiest resource for newcomers to come to grips with. If you're completely new to GitHub, or version control in general, then creating your first GitHub project and making your first commit, can be a challenge.
Even if you're a complete beginner who doesn't have a GitHub account, this article will get you to the point where you've created a GitHub repository, made your first commit, and have everything in place ready to continue developing your project.
The GitHub Workflow
The process of committing your first change to GitHub may sound long and complicated, but once you've got your environment setup correctly, making subsequent commits is much more straightforward.
Using GitHub, means downloading the Git version control system, and creating two repositories: one on the GitHub website, and one on your computer. After that, you'll work on your project as it exists in your local repository, while periodically committing your work to its corresponding GitHub repository.
Your local repository communicates with its GitHub counterpart via Git, so we'll start by downloading and configuring the Git version control software.
Installing and Setting up Git
Head over to http://git-scm.com/downloads and download Git. Note, although you can usually get a newer version of Git by building it from the source code, it's far quicker and easier just to grab the version that's packaged ready for download.
While Git is downloading, this is the perfect opportunity to create a GitHub account, if you haven't done so already.
Once Git has finished downloading, you'll need to let it know who you are, so it can add this information to all of your commits. Open your Mac's Terminal program (usually found in the /Applications/Utilities folder), and enter the following command:
git config -- global user.name "Name"
Next, tell Git the email address it should add to your commits:
git config -- global user.email "email@example.com"
Although there's additional tricks for configuring Git (for example, you can tell it to store your GitHub username and password so you don't need to keep entering this information) for now, this is all that's required to start using Git.
Create Your First Repository
GitHub stores each project in its own online repository, so the next step is creating this repository. Open your web browser of choice, log into your GitHub account, and do the following:
- In GitHub's upper-right corner, click the '+' icon, and select 'New Repository.'
Create New Repository
- Give your repository a name, and enter a description.
- Decide whether your repository should be public, or private. In most instances, you'll want your repository to be public, so other people can view, use, and maybe even contribute to it. Private repositories are visible only to you, and the other people you add to the repository. If you do want to create a private repository, you'll need to upgrade from a free account, to a 'Micro' account or higher. At the time of writing, a Micro account cost $7.00 per month.
- Choose your project's license, by opening the 'Add License' dropdown menu. If you're unsure which license is right for you, Choose a License has lots of useful information about the different licensing options.
- You'll notice an 'Initialize this repository with a README' option. Every GitHub project needs a README file, as this is the first place that potential users and contributors will look for information about your project. Since this file is so important, GitHub offers to create it for you automatically. Just select 'Initialize this repository…' and GitHub generates an empty README file, so all you need to do is enter some text. Normally, it makes sense to select this option, since you'll need to create a README file at some point anyway. However, creating, adding, and committing a README file manually, is a good introduction to the GitHub workflow, so this is exactly what we're going to do in this tutorial. Leave 'Initialize this repository….' blank, but just be aware that when you come to create subsequent repositories, GitHub can generate your README file for you.
- Click 'Create Repository.' You now have an empty GitHub repository, waiting patiently for your first commit.
Creating & Committing a README.md
As a GitHub user, you'll spend most of your time working on your project in a local repository, and committing your work to the project's corresponding GitHub repository at regular intervals. In this section, you'll experience this workflow first hand, by creating and committing a README.md file.
Before you get started, you'll need to create a local code repository, which is basically just a folder where you'll store your project. For the purposes of this tutorial, I'll be using a 'NewRepo' folder on my Desktop, but you can use a different folder name and location - just be aware that the Git commands will be slightly different.
Open your Terminal and change the default directory so that it's pointing towards your local repository/folder. This ensures the Terminal automatically applies all your commands to the 'NewRepo' folder, without you having to type its full path every time. To make this change, run the 'cd' ('change directory') command, followed by your local repository's path, for example:
At this point, 'NewRepo' is still just an unassuming folder on your computer. To transform 'NewRepo' into a local repository, you'll need to create a .git subdirectory that contains all of your repository's metadata. This may sound complicated, but it's actually achieved by running a single command:
Your 'NewRepo' folder is now an initialized repository that has the power to beam its contents directly into a GitHub repository. However, you haven't told your local repository which GitHub repository it should communicate with yet. To tell your local repository about its GitHub equivalent, run the following:
git remote add origin https://github.com/your_username/repo_name.git
Replace user_name with your GitHub username, and repo_name with the repository you want to send your commits to, for example:
git remote add origin https://github.com/JessicaThornsby/newrepo.git
From this point onwards, your local repository remembers which GitHub repo it needs to send any changes to, so you shouldn't need to run 'remote add' again.
At the moment, you still don't have anything to commit, so the next step is creating your README file:
"Touch" simply means "create," so if you want to add more files to your project, now's the perfect time, for example:
touch CONTRIBUTING.md touch LICENSE.md touch USER GUIDE.md
Check the 'NewRepo' folder, and you'll see a README.md file has appeared. Open this file and add whatever text you want, using your normal text editor.
When you're ready to commit your work, you need to let Git know which files it should include in the commit, using the 'git add' command. When you 'git add' a file, you're telling Git to add this file to a staging area, which is like a loading dock where you pick and choose which files are going to be shipped to GitHub. All new files, and any existing files you've updated, must be "staged," before you can commit them to GitHub.
To stage the README file, run the following command:
git add README.md
If you created more files besides README.md, then make sure to 'git add' these too.
Once you've told Git which files it should include in its next commit, you'll need to actually create said commit:
git commit -m "creating a README.md file''
The 'git commit' part of this command is self-explanatory, but the second part lets Git know that there's a log message to accompany this commit (-m), followed by the log message itself (in this example, it's "creating a README.md file"). A log message describes the changes that are included in the commit, which will be invaluable if you ever need to search your project's history for when a particular change occurred. If you're collaborating on a project with other people, commit messages are a way of ensuring everyone knows what's going on across the project as a whole.
The final step is sending this commit to the GitHub repository. As you develop your project, it's likely you'll create multiple branches, but you'll always have a main, or "master" branch that represents the stable version of your project. Since you haven't created any branches yet, this next step is very simple, as your only option is sending your commit to the master branch:
git push -u origin master
Enter your GitHub username and password, and Git will push the README.md to your GitHub repository. To check everything has gone smoothly, open your web browser and navigate to your GitHub repository - it'll now contain your README.md file.
Finding Out More
Obviously, there's much more to GitHub than creating and committing a single README file! But, if you've been following along, you'll now have a pair of connected repositories, so you're all set to expand on your barebones project by creating and editing files in 'NewRepo,' and committing these changes to GitHub.
If you want to learn more about expanding on this first GitHub project, you'll find lots of extra information at the official GitHub Help.