For those searching for a collaborative, open environment to develop software in, the well-known code-hosting website GitHub is a fantastic resource. With GitHub, you can make your project available for others to download, use, and eventually contribute to. Additionally, you get the added security of knowing that a copy of your project is stored on GitHub’s external servers, so you won’t lose all of your work if your local system breaks down.
Despite everything GitHub has to offer, it’s not the most user-friendly tool for beginners to learn. Creating your first GitHub project and committing your first change can be difficult if you are absolutely new to GitHub or version control in general.
Even if you are a total beginner without 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.
Table of Content
Things You Should Know To Create a Project on GitHub
- You have a PC or laptop with operating systems installed.
- You want to develop your project.
- You need to follow through the steps carefully to be able to reveal developer options.
Step 1: Installing and Setting up Git
Git can be downloaded from http://git-scm.com/downloads. It’s worth noting that, while you can usually get a newer version of Git by building it from source code, it’s far faster and easier to just grab the version that’s packaged and ready to download.
- While Git is downloading, now is a good time to create a GitHub account if you haven’t already.
- When Git has finished downloading, you must tell it who you are so that it can add this information to all of your commits. Enter the following command into your Mac’s Terminal program, usually located in the /Applications/Utilities folder:
git config -- global user.name "Name"
- Then, tell Git which email address it should include in your commits:
git config -- global user.email "email@example.com"
Step 2: Create your first Repository
Each project is stored in its own online repository on GitHub, so the next step is to create this repository. Open your preferred web browser, sign in to your GitHub account, and then do the following:
- In GitHub’s upper-right corner, click the ‘+‘ icon, and select ‘New Repository.’
- Enter a name for your repository and a description.
- Choose whether to make your repository public or private. In most cases, you’ll want your repository to be public so that others can view, use, and possibly contribute to it. Private repositories are only visible to you and those you add to the repository.
- If you want to create a private repository, you must upgrade from a free account to a ‘Micro‘ or higher account. A Micro account cost $7.00 per month at the time of writing.
- Open the ‘Add License‘ dropdown menu to select the license for your project.
- You’ll notice an option to ‘Initialize this repository with a README’. A README file is required for every GitHub project because it is the first place potential users and contributors will look for information about your project.
- Because this file is so vital, GitHub offers to generate it for you automatically. Simply select ‘Initialize this repository…‘ and GitHub will generate an empty README file for you to fill in with the text.
- Normally, choosing this option makes sense because you’ll need to create a README file at some point anyway.
- However, manually creating, adding, and committing a README file is a good introduction to the GitHub workflow, so that’s what you are going to do in this tutorial. Leave ‘Initialize this repository….‘ blank, but be aware that GitHub will generate your README file for you when you create subsequent repositories.
- Click the ‘Create Repository‘ button. You now have an empty GitHub repository, eagerly awaiting your first commit.
Step 3: Creating and Committing a README.md
As a GitHub user, you’ll spend the majority of your time working on your project in a local repository and regularly committing your work to the project’s corresponding GitHub repository. In this section, you’ll get a firsthand look at this workflow by creating and committing a README.md file.
Before you begin, you must create a local code repository, which is simply a folder in which you will store your project. For the purposes of this tutorial, ‘NewRepo‘ folder is used, but you can use a different folder name and location – just be aware that the Git commands will be slightly different.
Open the Terminal and change the default directory to point to your local repository/folder. This ensures that the Terminal applies all of your commands to the ‘NewRepo’ folder without requiring you to type its full path every time. To make this change, type ‘cd’ (‘change directory‘) followed by the path to your local repository, for example:
cd /Users/jessica/Desktop/NewRepo
‘NewRepo‘ is still an unassuming folder on your computer at this point. To convert ‘NewRepo‘ into a local repository, create a.git subdirectory containing all of your repository’s metadata. This may appear complicated, but it can be accomplished with a single command:
git init
Your ‘NewRepo‘ folder is now an initialized repository with the ability to directly beam its contents into a GitHub repository. However, you have not yet specified which GitHub repository your local repository should communicate with. Run the following commands to inform your local repository about its GitHub counterpart:
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 now on, your local repository will remember which GitHub repo it needs to send any changes to, so you shouldn’t have to run ‘remote add‘ again.
Because you have nothing to commit at the moment, the next step is to create your README file:
touch README.md
“Touch” simply means “create,” so now is the time to add more files to your project, for example:
touch CONTRIBUTING.md touch LICENSE.md touch USER GUIDE.md
Check the ‘NewRepo‘ folder for a README.md file. Open this file in your favorite text editor and add whatever text you want.
When you’re ready to commit your work, use the ‘git add‘ command to tell Git which files to include in the commit. When you ‘git add‘ a file, you’re telling Git to add it to a staging area, which is similar to a loading dock where you can select which files to ship to GitHub. Before you can commit new or updated files to GitHub, they must be “staged.”
To stage the README file, use the following command:
git add README.md
If you created additional files in addition to README.md, make sure to ‘git add‘ them as well.
After telling Git which files it should include in its next commit, you must actually create that commit:
git commit -m "creating a README.md file"
The ‘git commit‘ part of this command is self-explanatory, but the second part informs Git that there will be a log message accompanying this commit (-m), followed by the log message itself (in this example, “creating a README.md file“).
A log message describes the changes in the commit, which is useful if you ever need to search your project’s history for when a specific change occurred. If you’re working on a project with other people, commit messages are a great way to keep everyone up to date on what’s going on.
The final step is to commit this change to the GitHub repository. As you work on your project, you will most likely create multiple branches, but the main, or “master,” branch will always represent the stable version of your project. Because you haven’t yet created any branches, the next step is straightforward, as your only option is to commit to the master branch:
git push -u origin master
Enter your GitHub username and password, and Git will upload the README.md to your repository. To ensure that everything went as planned, open your web browser and navigate to your GitHub repository, which should now contain your README.md file.
Tips
Obviously, GitHub is much more than just writing and committing a single README file! However, if you’ve been following along, you’ll now have a pair of linked repositories, and you’re ready 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 your first GitHub project, you can do so by visiting the official GitHub Help.
