Overview

GitHub is a web-based repository service for Git. It provides all of functionality of command-line Git with a GUI interface, as well as additional features. A decent understanding of Git (version control, repositories, pushing/pulling, etc.) is necessary to efficiently use GitHub, so please take a look at the Git tutorial if you are unfamiliar. This page and tutorial are meant to be user-friendly, but some knowledge of Git is assumed.

Advantages

As stated above, GitHub offers the full functionality of Git and more. For those less familiar with the command-line, GitHub can provide a comfortable starting-point for using Git. Aside from this, there is the ability to explore the website for projects or repositories that you would like to contribute to, as well as a social networking aspect.

Disadvantages

Although GitHub does offer useful features, nothing can beat the simple efficiency of command-line tools. Using Git on the command-line will allow you to work with several files simultaneously without having to load a new webpage each time you want to view another file.

Creating a Repository

The first thing you will likely want to do upon creating a GitHub account is to create a repository. To do this, simply go to your "Repositories" sidebar on the right, and click "+ New repository":

This will take you to a page where you can name the repository, and choose some preliminary options, such as Public/Private, or automatically adding a README.md file.

Creating/Editing Files

After creating a repository, you will probably want to commit some code. One way to do this is to use the "HTTPS clone URL" provided on the right side of the window to commit your code from the command line.

You can also create and edit files within the browser window. To create a new file, simply click the blue + icon next to the repository name.

Editing a file within the browser can be done by simply clicking on the name of the file from the repository window, and then clicking the pencil icon at the top right of the file preview.

After creating or editing a file, you will see two options for committing the code at the bottom of the page. The first option is to simply merge the file directly into the master branch of the repository. For many situations, this is fine - the repository will just be updated with your code However, if you are working on a project with multiple people you may not want (or be allowed) to push your code directly to the master branch. In this case, you can create a new branch and pull request to request that the code be merged to the master branch.

#Markdown GitHub supports Markdown, which is a tool that allows you to write simple text with some formatting, which it then converts to valid HTML for web viewing. Any Markdown file committed to a GitHub repository can be viewed as HTML on GitHub. README.md files and wikis like this one are all written in Markdown, but you can also create your own Markdown files for anything you want.

For a good overview, check out the Markdown Basics page from GitHub.

GitHub Repository Toolbar

When inside of a repository on GitHub, you will see the repository toolbar on the right side of the page. This contains many useful tools in a repository. The toolbar looks like this:

From the top down, these icons are:

Code

The Code icon will take you to the main code page where you can view the contents of a repository. Aside from viewing the code in the current branch, you can view past commits and other data on the repository by using the bar above the code:

Issues

Issues can be created and viewed using the Issues icon. Issues in GitHub are a way to track bugs request changes, or just communicate within a team working on a specific project.

Pull requests

Pull requests are created to request that a certain branch or file be merged into another branch, often the master. A pull request can either be generated within an existing branch, or along with a new branch when committing code. After a pull request is generated, the other members of the repository can view and discuss it, and ultimately decide whether or not to merge the changes.

For more information, check out GitHub's extensive page on using pull requests

Wiki

Each GitHub repository comes equipped with its own wiki, which can be accessed via the toolbar icon. Pages can be added and edited from the wiki main page, and are written in Markdown.

Pulse

The Pulse feature in a repository shows a number of statistics about the repository which could be said to resemble its "health". These include proposed/merged pull requests, open/resolved issues, and contributions by the members of the repository.

Graphs

The Graphs page contains graphs over time of various repository statistics, including: contributors, traffic, commits, code frequency, punch card, network, and members.

Settings

Finally, the settings page allows you to change many of the repository settings including name, default branch, and toggling the wiki and issue features on/off. This is also where you can launch the page generator for GitHub Pages.

Contributing to a project

One of the key features of GitHub is the ability to discover and contribute to open-source projects, all without leaving GitHub itself. Using the search bar at the top, you can search for general terms and browse related public repositories. For example, a search for "artificial intelligence" resulted in the Open Cognition project. Their aim is to create a framework for Artificial General Intelligence.

Social features

GitHub provides a profile page where you can add a picture and some general info. Using this profile, you can "follow" and "be followed" by other users, which allows you to see each other's activity. The profile page also shows your GitHub contribution statistics.

GitHub Pages

Along with the profile page, each GitHub account comes with a free hosted website which can be generatued by creating a repository named USERNAME.github.io , and accessed by navigating to USERNAME.github.io in a browser.

You can choose to add your own HTML files to this repository, use Jekyll to generate the HTML, or use the GitHub automatic page generator. The GitHub automatic page generator is located under the settings for your USERNAME.github.io repository, and uses Markdown.

Activity

For your activity, you will be creating a new repository, adding a file, making changes to that file within the browser, and committing the code by merging directly with master as well as by creating and merging a pull request.

• Create a new repository with a name of your choosing
• Add a new file called helloworld.cpp
• Populate the file with your own helloworld code, or use the following:

Code:

#include <iostream
int main()
{
std::cout<<"Hello, world!\n"
}

• Commit the new file by merging directly to the master branch
• Edit the file again, and add some comments
• This time, create a new branch and pull request instead of merging directly with master
• View your open pull requests by clicking the Pull Request icon in the repository toolbar
• Open your recently created pull request
• View the changes by navigating to the "Files changed" tab
• Return to the "Converstation" tab and merge the pull request by clicking "Merge pull request"
• Since the branch is merged and no longer used, you can delete the branch by clicking "Delete branch"