If you stumbled here wondering, what the heck is GitHub? Let’s start with the fact that it's the largest single point or hub of open source and worldwide development. It uses a source code versioning system called Git, which is very powerful and lends itself well to open source communities.

On GitHub you’ll find all types of hidden gems that can help you become a better developer. I spend at least a few minutes each day browsing and looking for new projects, inspecting code, and learning from the community. In a nutshell, GitHub is by far the easiest way to manage your source code, project and documentation. So, let's take a look at some GitHub basics and how to get started.

Signing up

To start this GitHub tutorial for beginners, first sign up at the homepage. Be sure to choose your username wisely, and try not to use any special characters like dashes or underscores; readability is key. This username will be used in the links and navigation of all your projects going forward.

Your profile

Like any online profile, this section holds plenty of information about you, your activity and the projects you work on. Here’s an example of mine:

 

There are three main parts to your profile including personal information, repository information and contribution information. Your personal information is your avatar, contact information, followers, stars and organizations, while the Git repository information contains a list of all repositories with you’ve interacted. These are broken down into two categories titled "Personal" and "Contributed to." Personal repositories are all of the projects and source code that you've set up on your profile. If you do anything with another organization's project repository (repo), it will show up under the contributed to section.

Contributions are often seen as the gauge of activity on GitHub. Below your repository section is a blank graph. Each square turns darker green with more contributions for that day (here's an example of an active contribution graph). If your contributions don’t show when you push commits, you should make sure your email is set up in your git config on your development machine. If it doesn't match the email in your GitHub profile, you won't get credit for it.

Below that section is a contribution list. By clicking on one of the green blocks on your profile (or someone else's profile) you can filter and sort through the contributions for that day. This allows you to go to a specific contribution to inspect it, comment or modify it.

Finding projects

There are many reasons to search for projects on Github, and it’s extremely easy to do so. You might search to find a tool/code to use in your personal or team project, find a new project to contribute to or find an experienced and mature project to learn concepts from. To start, look for the search bar at the top of the screen. It has two modes: Global and Repository.

When you’re on global you can search by anything (cue Google). Let's search JavaScript. The first thing it will bring up is repo's with the name Javascript in them. This doesn't help us much, because we’re searching for something cool that has Javascript in it. But it’s a good stopping point to cover the sections of the search screen.

This too has several sections like the profile. On the left you get three immediate sections. Two of these help refine your search, and one gives you more information. The first shown in our example is the search type. You can use it to tell the search engine if you’re looking for repositories, text in code, text in issues, or a user. In this case we are looking for a repo so we will just leave it where it is.

The next section is a language selector. This helps you sort to only projects that contain the following languages. Since we searched JavaScript, it’s obviously at the top with 82,000 repositories. I'll go ahead and select it to refine our search a little.

Finally, on the left is the advanced search. You can play with that later if you want, but I wanted to point out the cheat sheet. It can be very useful in refining your search. I see that there is a cheat to showing repositories with a certain amount of stars. I'll go ahead and refine my search to have only repos with over 1000 stars.

Here are the new search results:

As you can see, the new search is much more refined. We went from about 130,000 repositories to just 497. There are a lot of different sorts, but since I'm looking for an active project I'm going to sort by Recently Updated. Take a look at the final outcome below, as this is what we'll choose for the next section of this post.

The project page

Now that we’ve discussed the search feature for finding projects on GitHub, let’s talk about the repository page. First off, GitHub has put a lot of work into the user interface and user experience of this page. We’ll cover the main parts of the repository homepage, along with some of the links. And then we’ll get into actually using this page when we discuss managing your project.

There are four main parts of the GitHub Project page. The top part (with links and menus), Project Information area, Source Code area and, finally, the README.md at the bottom. In the header, you’ll find links to Code, Issues, Pull Requests, Pulse and Graphs. Each of these has its own purpose:

• Code: The actual source code of the project


• Issues: Feature-Suggestions, bugs, enhancements, and conversation about the project.


• Pull Requests: Code that has been submitted to be part of the project.


• Pulse: Analytics and Overview of the activity of the project.


• Graphs: Deeper analytics and information about all sorts of project details.

You’ll also find three buttons known as Watch, Star and Fork. Take some time to get familiar with these:

• Watch: This allows you to receive notifications of all the activity on a repo. Be careful on watching highly active repositories or you will get an email inbox full of messages.


• Star: This is the like, love, favorite of GitHub. Marking this will bookmark this repository under your Stars area in your Personal Profile; remember that under your avatar.


• Fork: I think this is the most important button on the page. Fork is a concept of Git and source code contribution. If you're going to contribute to a project, you will have to fork it and make your edits in your own version of the code. GitHub Makes this easy by doing it for you when you press this button.

Below these three important buttons, you’ll see the project information area. This area shows the number of commits, branches, releases and contributors on the project.

• Commits: These are the base behind the Git Versioning system. Instead of pushing all of the code to the server each time you make changes, the system only stores what those changes are. This makes it easy to roll back and see what someone has actually done with the code. A commit is a package of all the changes made since the last commit.


• Branches: When working on a specific idea, you want to leave your main code alone. Here you can copy your code over to a new "Branch" and there you can make your changes without modifying the original. When you feel like you have good code, have tested it and want to move it back to the main branch, you can do that with a pull request. (More on that in the coming sections.)


• Releases: This is a version release; let GitHub know to mark this commit as full package. People can go here and download the code as it was on each release.


• Contributors: Contributors are people who have worked and helped maintain a project.

Clicking on the colored part beneath that bar will reveal statistics on the distribution of programming languages used in the program.

The next section allows you to traverse through the code in the project. But keep in mind that if you edit someone else's code note, it will fork it to your own repository for editing. If you were to click on a file, it would take you into the file editor. For example, if I click on AUTHORS.en.txt, it shows who submitted the latest commit, a line of contributors, how many lines of code, the file size, and more:

Note the buttons near the top right of the editor:

• Raw: This will open a new window and show the raw contents of the file. Allowing you to select it all to copy.


• Blame: This is another view of the code. It shows all the recent commits on the left with the code on the right, for each line of the code.


• History: This shows in chronological order the changes made to this file.


• Open in GH Desktop: This will download the file and open it in GitHub's desktop source control software.


• Edit: If this is your file, it will open the file for you to edit and update. If it's someone else's file, it will open it up in a fork for you to edit.


• Delete: Again, if this is your file it will just delete the file. If it's someone else's file, it will fork the project to your own repository and delete this file from it.

Back on the repo main page, you can see the section below the files which is called the README. This is the main documentation point for all repositories on GitHub. You use this to describe your project and more.

Creating a project

It's easy to create a project, just click the plus sign at the top of any page and choose New repository.

On the next page fill out the details. Click “initialize this repository with a README” (most of the time I choose the MIT License). If you click the info sign next to the license, GitHub can tell you all about the different types of licenses available. (Note: Due to GitHub's Terms of Service, you must use an open source license for public repositories). After you’ve filled it out you can click “Create repository.” Here’s my repository for this post:

Managing a project

Once you create a Git repository, you’ll need to manage it. There is a lot that goes with managing a GitHub repository, but I promise it’s nothing you can’t handle. Let’s walk through it together.

Readme

First, set up a README.md. This is located in the root directory of your project and can be easily edited in the browser. The readme uses Markdown Syntax (learn more about that here). The Readme should have basic information about your project. How to download it and use it, as well as other small tasks to be performed. Check out this solid example of a readme.

For this readme, we'll just describe the repository. Here's my markdown for it:

The-Definitive-Guide-To-Github   This is the repo used in an article published to Pluralsight. I’m making this repository to allow others to view it after reading the article. It also allows me to do screenshots and perform actions alongside writing the post -- this is good practice to make sure I don't miss anything. You can find the article at [This link](http://insertarticlelinkehere)

You can do a lot while editing this file including previewing changes and changing the name. When you’re done editing you need to name your commit (remember, you’re pushing changes, so this will be packaged as a commit and put in your repository) and a description of what you changed. You can see what I’ve done here:

When I save that, I'll have an updated readme page on the repository:

Issues

Issues are probably the second most important part of GitHub. Issues make things like managing bugs and feature requests a cinch. First you should know that open issues are green and closed issues are red. To create a new issue just hit the big, green “New issue” button. Give your issue a title, and then describe it. This can be anything from a bug, an enhancement, a call for help wanted, or even just a question. These descriptions are known as Labels; labels can be selected on the right. You can also select a milestone if you’ve created one, or assign someone. (Please note that some of these actions require you to be an owner of a repository.) Once you’re done, click “Submit new issue.”

You can view details about an issue directly from the issue page, including all the fields we just populated when submitting the issue. You can link issues to each other using #issuenumber and link to commits using the “commit hash.” This is where you’ll have the discussion of your issue for further conversations, up until it’s closed.

Here’s an example of an active issue board:

Milestones

You can access milestones within the issues area. You can use these to segment and plan your project. Just set up a name and due date, and then issues can be assigned to milestones, allowing you to store and manage issues easily.

Wiki vs. GitHub Pages

Wiki pages serve as a separate area to store your documentation in markdown format. This separates your code from your documentation; however, depending on your personal preferences, this could be good or bad. It should be noted that most new projects use GitHub pages for documentation because this allows for the use of documentation generators like Mr-Doc to generate the html pages from comments in your source code. While the wiki can be a quick way to get your documentation started, I recommend using GitHub Pages.

GitHub Pages is one of the newer additions to the GitHub platform. It allows you to server static websites for free (this has led me to drop all of my paid hosting and moved everything to GitHub pages). The system uses a software called Jekyll to generate and maintain the static files, and it’s easy to use. You can learn about Jekyll here, but in the meantime, think of it like WordPress for the command line.

To use GitHub Pages all you have to do is create a new Branch in your repository called “gh-pages.” Drop your static Web files (html, css, js, images) into the branch and it will be served over a URL like http://your-username.github.io/repository-name. It's as simple as that! Oh, and as a bonus, GitHub lets you use your own domain name for free; use that to host your full site at a domain name of your choosing.

Building a community

I'd guess that more than half of the repositories on GitHub are open source projects. Open source projects tend to work well for communities, and because of this you’ll want to provide ways for your community to grow. Let’s look at a few different ways you can do that.

Integrate with Slack

Slack is a great communication tool, and perhaps one of the hottest at the moment. It's free to use and set up, and with some well programmed API's it can become a great community. I prefer Slack because it can be used for multiple projects, has a mobile app, and is simple to use. You can also integrate Slack with GitHub by using a service called, If This Then That. IFTTT allows you to build triggers. I have many setup for my team's Slack (like when a new issue gets posted to any of my GitHub repositories, it automatically notifies people through Slack).

Integrate with Trello

Trello is a good tool to keep your project organized. You can use it to organize cards into categories. This could be a new feature in the In Progress category. I have used an IFTTT flow to post new issues to a Trello Board where I can then work them and move them through my task management workflow.

Integrate with Gitter

Gitter is an alternate to Slack. I haven’t used it much, though many repositories do. One thing to keep in mind is that if you work behind a corporate firewall, they may block ".im" domain names.

Contributing to projects

This may very well be the strongest part of GitHub. For the rest of this post, we’ll look at contributions and how to use Git.

Fork

Before you start helping with a project you should first check with the owner of the repository for things that need to be done. Sure, you can add your ideas into the mix, but if there are major things that need work, it’s better to start there. After you decide to contribute and have an idea of what you want to do, you’ll want to fork the repository; this will copy the repository to your own personal repository. Here you can clone the repository (more on that below), make your changes, and push them back to your repository. You can do this as long as you want, but keep in mind that the repository that you forked from will keep on changing. Make sure you keep your code synced with changes that are happening with the main repository.

Pull request

Once you’ve finished making changes to your repository, tested them, and are confident they’re ready, you’ll need to submit a pull request. I'll go ahead and make a small change to a Pluralsight Tutorial and submit a pull request so you can see how that looks. You can see below that when I clicked to edit an article in the repository, GitHub forked it for me. Now when I save it I'll be ready to submit a pull request.

Based on personal preference, I’ll then go through and update code blocks in this file to have syntax highlighting. After I’m done editing I'll add a title and description and click “propose file change.”

After clicking that, I’ll see a comparing changes page where I can see that I changed one file and added 15 new lines of code. You can also see that I’m going to submit a merge request (pull request) from my head fork of “shadowcodex/tutorials” to the base fork of “pluralsight/tutorials.” Next, I’ll hit the green “Create pull request” button and submit it.

Next, I’ll be asked to title and comment my pull request. GitHub was nice enough to prefill these from my propose file changes area. I'll just go ahead and say it’s good enough and click the green “Create pull request’ button to finish the submission.

This is how the end of my contribution looks:

Git Basics: Introduction to Git

As briefly mentioned earlier, Git is a source code control system. It has been designed to work for everything from small to large scale projects. It's easy and efficient. To get a full understanding of Git you can head here. To break it down, the concept you’ll follow about 90 percent of the time is this:

1. Clone


2. Make Changes


3. Commit


4. Push Commit to Server

or

1. Fork


2. Clone


3. Make Changes


4. Commit


5. Push Commit to Server


6. Submit Pull Request

Cloning

When you create your project on GitHub you’ll notice on its home page a link that looks like this:

Once you have Git installed all you have to do to get this code onto your machine is run the following command using that link.

shell   $ git clone https://your-github-link

This will copy the entire master branch (or your default branch) to your local machine.

Commit

Once you’ve cloned your repository you’re free to make changes to the files. After you’re done you’ll want to push the changes back to GitHub. To do this we’re going to make a commit which will store all the changes into a package ready to be pushed to the server. The following commands will add all the changes to a commit for you. (Make sure you’re in the root directory of your project before running these commands.)

The first command adds all the files to your stage and prepares to commit them:

shell   $ git add .

If you have deleted files, you may get an error when running this command. That's OK, just run the following command instead:

shell   $ git add . --all

You are now ready to make your commit using this command:

shell   $ git commit -m 'enter your commit message here describing what you did'

Your commit should now be ready to go! You can have as many commits as you want on your local machine (I do commits when I finish major parts of the project). Once you do a push, it will push all the commits that aren't synced to the server.

Push

Now that you have your commit ready you’ll want to push it to the server, which is easily done with this command:

shell   $ git push

It will ask you for your username and password. Once you’ve entered those correctly it will push all commits to the server, and you're done!

Pull

If you make changes on the remote repository, you’ll want to get those changes into your local repository (assuming you’ve already cloned it). You can do this with the pull command:

shell   $ git pull

Checkout

 

If you have created a branch to work with on GitHub, you can easily switch to that branch on your local machine by running the following command:

Tshell   $ git checkout your-branch-name

Also, I recommend that Git and GitHub beginners do all pull requests on the website; this makes it easier.

Takeaway

OK, so that was a ton of information at once, but before you begin to feel overwhelmed, remember that learning GitHub, just as learning anything new, takes time. Use this guide as a map while navigating your way through GitHub and you'll be well on your way to mastering it far more quickly than you could have imagined. Once you feel like you've started to know how to use GitHub and you've got a firm handle on it all, be sure to check more Pluralsight tutorials and take your skills to the next level.