GitHub Basics
Advanced Data Analytics

1 What is GitHub?

GitHub is a git repository hosting service and web-based, collaborative version-control platform for developers. While GitHub offers a suite of features, in this course we will primarily use GitHub for cloud-based hosting of our coding projects. For this exercise, we will learn how to:

• Create a Github account
• Create a blank repository
• Integrate with RStudio
• Create and commit changes through the RStudio Git tab
• View Changes on GitHub
• Create a project webpage in GitHub

GitHub is generally used for version control, working on collaborative projects, creating websites, developing and sharing teaching tools, software development, and code development, but is generally not good for storing or manipulating large datasets.

1.1 Create GitHub Account

To begin, you will need to create an account on GitHub.com. This will allow you to create, fork, share, collaborate, etc. on projects.

Image of the GitHub Sign-Up Window

1.2 Create Repository

Once you have created an account you can navigate to repositories and click on the green button for a new repository.

Image of the Repository Bar to create new repository

Create a name for the repository, for this example we will use GitHub-Basics, provide a description, be sure to make the repository public, turn off the “Add README” (for this example; it might be necessary to turn this on in the future), add a .gitignore file using the R filter in the drop-down menu. For now you can ignore the add license option and create the repository by clicking create repository.

1.2.1 Copy Repository Link

Once you create your new repository you should be taken to the home page for the repo.

Image of Code Button option to copy repository link

This link will be used in RStudio to connect your project to the GitHub repository. At this point you can move to RStudio but keep the GitHub window open so you can refer back to see changes you have made during this example.

2 Integration with RStudio

RStudio has integrated version control and allows you to clone a project from any Git repository. For this example we will use the link obtained in the above step to integrate local changes with the GitHub repository we created.

While the following steps will use the GUI interface in RStudio, the majority of these steps can also be completed in GitHub Desktop or in the command line.

2.1 New Project

To begin we will create a new project using the File > New Project command. In previous examples the New Directory option was used, but in this exercise we will instead use the Version Control option.

Image of the RStudio Version Control options

2.1.1 Version Control

This option will provide us the ability to choose between Git and Apache Subversion. We will follow the option for using Git as we learned in the previous exercise.

Image of the Version Control window

2.1.2 Git for Versioning in RStudio

The version control option will allow you to obtain a project from a version control repository such as GitHub.

If you want to bring an already developed repository into RStudio in a blank project, from the terminal you can use the git command git clone <GitHub Link> in the folder you wish to store the repository and then save as a new project.

2.1.3 Create Project

Before you finalize your project, you will be prompted to including the following information:

Image of the Clone Repository window

- Repository URL - Here you will paste the link you copied from GitHub: http://github.com/username/repository - Project Directory Name - This is the folder that will be created to organize the project. - Tip: Making this the same as the repository name will help keep you organized between the local and online environment - Subdirectory - This is the local root directory where the project folder will reside. For example, if you want the project folder to be housed within the Ex-8 folder on the Z drive you would browse to: z:/students/name/Ex-8 and then click create project.

2.2 View Project in RStudio

This will open the typical RStudio Project window you are used to seeing including the project information in the upper-right corner, project files in the files tile, etc. but you will also now see a new Git tab alongside the “Environment-History-Connections” section. It is in this tab that we will control the integration for our local project and online repository.

Image of RStudio Project Window

2.2.1 Git Tab

In the Git tab you will notice several options including:

• Diff which details the difference between versions of a file.
• Commit which allows us to initial a commit similar to the git commit command in the previous exercise.
• Blue down arrow for a pull command
• Green up arrow for a push command
• Clock to view a history of the commits
• Gear that allows you to revert to previous stages
• New branch icon
• Branch information showing which branch is currently being edited
• Refresh icon

2.2.1.1 Staged Files

There are two ways to stage files in RStudio. The first is directly from the Git tab. By click on the button in the “Staged” column, you will see the icon in the “Status” column change. The second is by clicking the “commit button” and staging the files from there. Because of the simple interface, files can easily be staged/unstaged from either location.

You could also complete many of these steps via command line from the terminal window.

2.2.1.2 Color-coded Icons

In RStudio as you stage files their icon will change to match their current status. You are most likely to see the following information:

• Yellow box for newly created/untracked files
• Blue box for files that have been modified
• Green box for files that have been added/staged and are ready for a commit
• Red box for files that have been deleted

Once you have the files appropriately staged, you are ready to commit them to your repository.

2.2.2 Commit and Push to GitHub

In the commit window you can stage files, view differences in the changed files, add a commit message, and push your changes to the remote repository.

It is important to always include a commit message each time you commit files to your repository. As we have seen in the previous exercise, this helps to keep track of each stage of development and informs collaborators of changes made in each update. Because RStudio provides a text box for commits, there is ample room for an appropriate commit message. Check out these suggestions about composing better commit messages: Chris Beams’ Commit messages matter. Here’s how to write them well!

After staging your files and writing a useful commit message your next step will be to commit that information. Remember even though you have your local and GitHub repositories linked, you are only making this commit to the local repository. In order to sync the two repositories you must Push the changes to GitHub.

2.3 View Changes on GitHub

Once you have completed these steps you can navigate back to your GitHub repository and view the information you have just pushed to the repository.

Image of Updated GitHub Page

2.4 Create a GitHub.io webpage

One excellent feature of GitHub is the ability to create webpages out of content within your repository. This is an extremely easy process and at this point each of the exercises you have completed in the course can be turned into a webpage with very little effort. In the setting menu of your repository, scroll down to the section for GitHub Pages and in the “Source” portion, change from GitHub Actions to Deploy from a Branch.

Image of the GitHub Pages Settings

This will slightly alter the look of the page and you should see a new branch section where Master is selected as the root directory.

Image of the GitHub Branch Settings

This will enable a webpage for your repository that utilizes a consistent url theme:

http://username.github.io/repository name

In order to create a webpage using GitHub Pages, simply create a copy of your *.nb.html and call it index.html. Once the index.html file is created, push it to your master repository and the website will automatically be created.

It may take several minutes before the site appears on your github.io page for the first time.

3 Your Turn!

While there are a number of features an options available in GitHub, here we covered only the basics of creating and maintaining a repository and enabling GitHub Pages. At the end of the semester your final project will be to develop materials based on your thesis research. So for this exercise I want you to create a repository and GitHub webpage for your thesis work. You should create a README.md file for your project that includes:

• Project Title
• Project Abstract
• Link to the Github.io page
• Repository Description
• References

This repository and webpage should be periodically updated throughout the remainder of the semester culminating in your final project. You should take a look at the various options and features (such as themes, notifications, social previews, wikis, projects, etc.) available in to create a useful repository for sharing and maintaining your project.

3.1 Additional Help

Colt Steele has a great series of tutorials on a number of coding related topics including Git and GitHub. This GitHub tutorial, called Learn Github in 20 Minutes, walks you through many of the steps we discussed in class and covers topics that are slightly more advanced than you might need in the near future.