GitHub for Data Scientists without the terminal
by Sahir Bhatnagar
The first three steps are similar to those from creating a basic R Markdown website: Create a GitHub repository named YOURGHNAME.github.io, where YOURGHNAME is your GitHub username, initialized with a README file Clone the GitHub repo to a local directory with the same name Add an R Project to the local directoroy. Feb 10, 2018 github This tutorial teaches you to create R Markdown documents with RStudio and publish them via GitHub, using GitHub Pages. RStudio is a popular integrated development environment for R. It integrates the tools you use with R into a single environment. R Markdown is a file format for making dynamic documents with R. An R Markdown document is written in markdown (an easy-to-write plain text format) and contains chunks of embedded code. R Markdown files are designed to be used with the rmarkdown package. Rmarkdown comes installed with the RStudio IDE. Dec 23, 2018 If you mean you would like to use GitHub pages to publish or deploy your bookdown project and: a) you would like to place the rendered book (i.e., the folder book is not in your.gitignore file) on GitHub b) further, you are OK with placing your rendered book in a folder on your 'master' GitHub branch. While it's not possible to host fully-fledged Shiny apps on Github pages (Indeed, as @Gregor suggested, shinyapps.io is useful for this), the devs for Shiny have been working to make some of the functionality run completely on the client-side via htmlwidgets.
In this tutorial you will learn how to get started with version control usingGit and GitHub. The main goalhere is to provide a step-by-step introduction to GitHub, with detailedscreenshots, so that you become familiar with its main functionalities.
This tutorial is intended for grad students and academics who use
R but are unfamiliar with the command lineor terminal. I assume nothing about the computer science skills of the user, but doassume basic knowledge of
The outline is provided below. You will learn the essentialconcepts and terminology of version control, Git, GitHub and GitHub desktop. Thistutorial follows a learn-by-doing approach.
- Installing Git
- Signup for a GitHub account and a Hello World tutorial
- Installing GitHub Desktop
- Version control
Rcode using an example of PCA
- Create a branch, pull request and merge
- Introduction to Git functionality in RStudio
- Create and publish an
- Create an online CV
Familiarity with GitHub has become an indispensible tool for anyone workingwith data. Sharing code, writing software for your statistical method,producing techincal reports and creating websites have become essentialskills to have in the rapidly growing field of data science.Other answers can be foundhere,hereand here.
Each of the topics covered are separated by chapters that should be followedsequentially. Within each chapter, there are a series of steps that you needto complete. Each step starts with some instructions followed by a screenshot.
Chapters 1-3 have no pre-requisites in terms of software. Chapters 4-8 require a workinginstallation of
What this isn't
It is not a comprehensive tutorial of all the intracacies of Git. I skip overmany fine details, because the main goal of this tutorial is an introductionto essential concepts and terminology of version control, Git, and GitHub.
It covers a variety of topics that could each be its own book. There are a plethora ofonline resources available for everything covered here but you can't Google somethingif you don't know what you're looking for in the first place.
There are several more advanced and comprehensive online resources available forlearning git and github for data science oriented people including:
The main difference here is that we don't use the terminal (or command line) andprovide screenshots for every step.
Chapter 1: Installing Git
Git is to GitHub, what R is to RStudio. In other words Git is the software thatdoes all the work behind the scenes, and GitHub a user interface that makes itseasier to communicate with Git (and adds functionality as well). In this chapterwe will download and install Git.
Note: the screenshots provided here are from a Windows operating system, however it will be similar on a Mac or Linux.
Once the download has completed, click on the
Git-2.7.4 64-bit.exe file(
.dmg on a Mac, or
.deb on Linux). Note: the version you download might be different than what I've shown here, but that's ok
Once you have read the GNU General Public License (this is not requiredto continue) click on
You need to select where you want Git installed. I have chosen the defaultlocation
Program Files, but you can change this if you like by clicking onthe
Browse... button. Once you have chosen a location click
Select the components you want to install. Ensure that at least the boxesshown in the screenshot below have been checked. Click
This step is to select where you want the shortcut location to be stored. Ihave chosen the default. Then click
Git can be used from the command line also. Selecting the second option allowsyou this flexibility for when you become familiar with Git.Note: you might see different options on a Mac, if you don't know which option to choose, select the default
Select the (recommended) first option and click
Next.Note: you might see different options on a Mac, if you don't know which option to choose, select the default
Select the (recommended) first option and click
Next.Note: you might see different options on a Mac, if you don't know which option to choose, select the default
Ensure that at least the
Enable Git Credential Manager box is checked, and click
You should see now see the following installation screen.
The following screen will appear once the Git setup has successfully completed.Click on
Finish. Well done, you have installed Git on your system. Proceedto Chapter 2 to signup for a GitHub account.
Chapter 2: Signup for a GitHub account and a Hello World tutorial
In this short Chapter, you will signup for a GitHub account. GitHub is likeyour online portfolio of code. It has a plethora of great features for creatingwebsites, project pages and collaborating with others. Again GitHub is aninterface to the version control system called Git. Other optionsinclude Bitbucket and GitLab.
Go to https://github.com/.
The longest step in this chapter is choosing your username. Think about itcarefully and ensure that its professional; it will be how you are recognized on the internet, i.e., your github website address will be github.com/username. Once you have chosen a username, enter a valid email address and password, and click on the
Sign up for GitHub button.
Choose the free plan (default) and click on the
Finish sign up button.
Well done. You now have a GitHub account. Complete the
Hello World guidewhich will walk you through some functionalities of GitHub. Click onthe
Let's get started! button.
Complete the exercises in the Hello World tutorial and move on to Chapter 3: Installing GitHub Desktop.
Chapter 3: Installing GitHub Desktop
Traditionally, version control with Git is accessed through the command line orterminal. GitHub Desktop is a software program that makes it easier to use Gitfunctions without having to use the command line. It also allows you tocommunicate with your GitHub website (github.com/username). Don't worry if thedifferences between Git, GitHub and GitHub Desktop are not clear to you yet.You will have a better understanding once you have completed this tutorial.
Note: in all the screenshots that follow, my username is shown, however you should be entering your username, password and email address created in Chapter 2.
Go to https://desktop.github.com/ and clickon
Download GitHub Desktop.Note: GitHub desktop is only available for Windows and Mac. If you are running Linux I recommend GitKraken.
Once the program has finished downloading, click on
.dmg on a Mac).
You should see this installation screen.
Once installed, open up the program and login using the GitHub username andpassword you created in Chapter 2 and click on
This information is used to identify the person that made the changes to yourcode. Leave the default values and click on
You should see this screen, since you haven't created any local repositories yet.
What is a repository? The purpose of Git is to manage a project, or a set of files, as they change over time. Git stores this information in a data structure called a repository (reference).
You should now be at this screen.
Click on the button in the top left corner. Your username should appearwith a list of your repositories that are currently saved in your online GitHubaccount. To be able to have a local copy of this repository (by local I mean onyour computer hard drive) click on the
Clone tab and thenthe
Clone hello-world button (I am assuming that you completed the
Hello Worldtutorial in Step 5 of Chapter 2).
Choose where you want to save a local copy of the
Hello World repository and click
You should now see the following contents in your GitHub desktop program.
Using your computer's file explorer (e.g. windows explorer or mac finder),locate the local GitHub repository. If you successfully cloned your repositoryyou will see a
hello-world folder with a
README.md file in it, which isthe same one you created during the
Hello World exercise in Chapter 2.
Before moving on to Chapter 4, verify that the GitHub Desktop has added anSSH key for you. An SSH key is used to establish a secure connection betweenyour computer and the online GitHub server. On the far top right hand side ofyour online GitHub account click on the icon and navigate to
You should see one entry in the
SSH keys panel. Well done. You are now readyto version control some
R code in Chapter 4.
Chapter 4: Version control R code using an example of PCA
In this chapter we will learn how to version control
R code using an exampleof Principal Component Analysis.
Create a local (meaning on your computer) repository by clickling the button in the top left corner of GitHub Desktop, and select the
Create tab.Name the repository
pcaCars and select where you want this repository storedon your computer. Leave the
Git ignore value at its default (we will ignore whatthis is for now). Click on .
You should see the following in your GitHub Desktop. A repository called
pcaCars has been created locally on your computer, and it contains twotext files that were automatically created by the software. You can click on themto see their contents. The most important of the two is the
.gitignore file.This text file allows you to control what you want to version control within the
We now want to publish this repository to the remote (i.e. github.com/username).Simply click on the button in the top right hand corner. Add a descriptionand click on .
Head over to your online github account (e.g. https://github.com/git4ds).You should see the
pcaCars repository along with the description you entered in theprevious step.
Click on the
pcaCars repository and you will see the
.gitignore files which are the same ones you have in your local repository.
Open RStudio, navigate to the
pcaCars repository and set it as your workingdirectory using the
Save the following code in an R script called
Go back to GitHub Desktop. You will see the
pca.R file appear. Click on thecheckbox to the left of it, and you will see all the additions you have madeto the file.
On the bottom left hand side, enter a summary of the changes you have made tothe repository and an (optional) description. Then click on .This is essentially telling Git to record the changes you have made and store themin a branch. We will learn about branches in Chapter 5.
You should see the following screen. You should notice that in the rectangularblack box, underneath the button,a timeline. As you commit additional changes, this timeline will grow. Each circle representsa snapshot of the repository at the time of the commit. This is the power of version controlling withGit. You can see what changes you have made, and even revert back to snapshot you want.
Go to the
pcaCars repository in your online GitHub account. Do you see thefile you just created called
pca.R ? Why not? Because the commit you made was localto your computer. In order to see these changes online, you must
push your localchanges to the
Go to GitHub Desktop and click on the button in the top right hand corner.
You should now see your local changes pushed to your online repository.
Let's make a change to the
pca.R script. Instead of a scree plot, we wanta bar plot of the variance explained for each component:
Your script should now match what is shown in the screenshot below.
Go to GitHub Desktop and click on the
pca.R file. You will see thatGit automatically recognizes the changes you have made. Highlighted in redis what has been removed from the file, and in green is what was added.
Describe the change you have made and click on
Push your local changes to the remote repository by clicking on the button. You can view the different commits you have made in GitHub Desktop by clicking onthe grey circles in the timeline located in the rectangular black box.
Go to your GitHub account online to see that the changes have been updated. Click on the
History button located in to see a list of commits you have made to the repository.
History of commits you have made to the repository.
Chapter 5: Create a branch, pull request and merge
In this chapter you will learn what the words
pull request and
merge meanin the GitHub world. Branching is a much more efficient and safe alternative tohaving files in a project like this:
This image (source)nicely summarises what branching is useful for:
When you have a new idea, or want to test out some existing method but don't want tomodify your working script, then creating a branch is what you should do.
A branch represents an independent line of development. You can think ofthem as a way to request a brand new working directory (reference).
Click on the branch symbol andname the branch
From branch entry indicates what the starting point of the
clusteringbranch should be (you will see what this means shortly). Since there are no other branchespresent,
master is chosen by default. Click on .
You have now switched to the
clustering branch. Notice the second timelinelabelled
clustering underneath the
master in the black rectangular box.
You will also see a list of branches in this repository in the dropdown listnext to the branch symbol .The checkmark indicates the branch you are currently on.
The motivation for creating this branch is that we want test out some codeto cluster the cars based on principal component scores. Go to RStudio and addthe following code to
pca.R and save the file. You will need to install the
ggrepel packages from CRAN
Go to GitHub Desktop, click on the
pca.R file and you will see the changes madehave been highlighted. Describe the changes you have made and then click on.
Push your local change to your online GitHub repository (i.e. the remote)by clicking on the button.
You will see the
clustering branch appear in the
Branch dropdown menu.
clustering branch and confirm that your changes to the
pca.R scriptare there.
Switch back to the
master branch. Why isn't the clutering code there? Becauseyou commit your changes to the
clustering branch and not the
master branch.It should become a little more clear now what branching is and it's utility.
If you're content with the clustering results, it's time to merge the clustering codewhich is sitting on the
clustering branch with the PCA code on the
master branch.This is accomplished via a
pull request. A
pull request is the first step in merging two branches.It tells GitHub that you have committed changes to the repository and allows you to review the changes.Note:
pull requests are a GitHub functionality and is not part of Git.
Click on the button in GitHub Desktop, enter a summary and descriptionof the proposed changes and why you did them. Then click on .
View it on GitHub. This will open the submitted
pull request in the
pcaCars repository of your online GitHub account.
GitHub will automatically check that the merge can be completed without anyconflicts. If there are no conflicts you will see the following screen. Click on.
Enter a comment about the pull request (optional) and click on .
Well done. You have successfully created a branch, submitted a pull request andmerged your changes from the
clustering branch to the
master branch. You candelete the
clustering branch by clicking on as it is no longer needed because these changesare now in the
Branch dropdown list you will only see the
master branch. You willalso notice that the clustering code has been merged with the PCA code.
The merge was done online. We now want to see these changes reflected on ourcomputer (i.e. locally). To do this, go to GitHub Desktop and click onthe button.
Notice that the
clustering branch still exists even though you delete itin your online GitHub repository. Why? Because you did not delete the branchlocally (i.e. it still exists on your computer). Click on the settings dropdown menuand select
You will now only see the master branch in both the dropdown list and the blackrectangular box.
Chapter 6: Introduction to Git functionality in Rstudio
RStudio also has the ability to interact with Git and GitHub, similar toGitHub Desktop. I will briefly show how to initiate this by creating an
RStudio project. More comprehensive resources can be foundhere andhere.
In RStudio go to
File -> New Project ...
Choose the second option:
Existing Directory and select the folder whichcontains the
Git tab in located in the top right panel. It is emptybecause no changes have been made to the repositor.
We don't want to version control the files associated with the RStudio project.Open the
Add the names of these files in the
.gitignore text file as shown in thescreenshot below and save the file.
Git tab you will now notice the
.gitignore file has appeared becauseyou have made changes to it.
You will also notice these changes in GitHub Desktop.
Describe the commit and click on .
Sync the local repository with the remote by clicking on the button.
RStudio can also handle branches. To see this, click on the branch symbol, and createa branch called
gh-pages. To do this, enter
gh-pages in the Name field and click on
In RStudio you should see a dropdown list of branches in the top right handcorner of the
Git panel. You should now be in the
gh-pages branch for Chapter 7.Note: this branch must be called
gh-pages; you will find out why in the next chapter
Chapter 7: Create and publish an R Markdown document
In this chapter you will learn how to create an HTML report (of the PCA you did inearlier chapters) using
R Markdown. You willthen learn how to publish this report online. The following steps must be completed on the
In RStudio, click on the dropdownlist and select
If you don't have the required packages, RStudio will automatically install them.Click
This screen appears to indicate the installation of required packages to use
Enter a title and author. Ensure that the
Default Output Format is HTML.Click on
To ensure everything is working correctly compile the document by clicking onthe button.This will convert the
R Markdown document to HTML.
You will be prompted to save the file. It must be saved as
If everything is working properly, an HTML document named
index.html will appear.This is the HTML report, also called a dynamic document that contains both
R code and text.
R Markdown Download
I have created a sample report which you can see here.Copy the contents of that report and paste it into the
index.Rmd file, replacing its entire contents.Click on the button.
The HTML document will automatically load after the document has finished compiling. You can viewthis document in your web browser by clicking the
Open in Browser button.
Note the location and filename of the document. It is currently only on your computer, andhas not been published online.
Both RStudio and GitHub Desktop have noticed the changes you made to the
In GitHub Desktop, select all the files that have been changed or added, describe the changesand click on
Publish the local changes to your online GitHub repository by clicking the button in GitHub Desktop.
Head over to the
pcaCars repository in your online GitHub account. Click on the
Branch dropdown list and select the
Notice that the
R Markdown, HTML and related files only appear in the
gh-pagesbranch because that where you committed them.
Click on the
Settings tab. You will see a box called
GitHub Pages which saysthat your site has been published at
http://username.github.io/pcaCars. Click on thesite to verify that the report has indeed been published online.
Well done. The report has been published online. This makes it extremely easy to sendreports to your supervisor or collaborators, without having to send large email attachments withlong names indicating the version. Simply commit new changes to the repository, and the reportwill automatically get updated online.
The website link never changes, and you can simply sendan email to your supervisor or collaborators indicating that changes have been made to thedocument.
There are four important things to note:
- The html document that you want to publish must be on the
gh-pagesbranch.See https://pages.github.com/ for more details.
- The html document must be named
- The name of the website will always have this format: http://username.github.io/nameofrepository
- Every repository you create can have its own website. Let's test this in Chapter 8.
Chapter 8: Create an online CV
In this chapter you will learn how to create an online CV. The template I haveshown is for illustration purposes. The main objective here is for you to have a websitethat has your CV. I highly recommend the advice given by Sherri Roseon Academic CVs for Statistical Science Faculty Positions.
In GitHub Desktop, create a new repository called
cv. Click on
gh-pages branch and click on
Save the template CV in thenewly created
cv repository on your computer (source).Open the file in RStudio and click onthe button.
Commit the changes in GitHub Desktop. Describe the changes you made and click on .
Click on to push your changes to your online GitHub account.
After entering a description of the repository click on .
Your GitHub Desktop should now be clean.
Go to your online GitHub account and navigate to the
In setting you should see that your site has been published.
Well done. You now have an online CV.
This concludes the tutorial. Well done.
GitHub has evolved into a necessary tool for anyone doing data analysis. It is not uncommon now for employers to prioritize your GitHub portfolio over your CV. This tutorial demonstrates how simple it is to get up and running with GitHub. In addition to having an easy-to-use interface, it allows you to easily create websites and host dynamic documents. I encourage you to adopt this workflow, whether you work in industry or academia, to showcase your work, increase efficiency and ensure reproducibility.
What About Dash?
Learn about how to install Dash for R at https://dashr.plot.ly/installation.
Everywhere in this page that you see
fig, you can display the same figure in a Dash for R application by passing it to the
figure argument of the
Graph component from the built-in
dashCoreComponents package like this:
3.2 GitHub Pages
GitHub Pages (https://pages.github.com) is a very popular way to host static websites (especially those built with Jekyll), but its advantages are not obvious or appealing compared to Netlify. We recommend that you consider Netlify + Hugo due to these reasons:
Redirecting URLs is awkward with GitHub Pages but much more straightforward with Netlify.38 This is important especially when you have an old website that you want to migrate to Hugo; some links may be broken, in which case you can easily redirect them with Netlify.
One of the best features of Netlify that is not available with GitHub Pages is that Netlify can generate a unique website for preview when a GitHub pull request is submitted to your GitHub repository. This is extremely useful when someone else (or even yourself) proposes changes to your website, since you have a chance to see what the website would look like before you merge the pull request.
Basically, Netlify can do everything that GitHub Pages can, but there is still one little missing feature, which is closely tied to GitHub itself, which is GitHub Project Pages. This feature allows you to have project websites in separate repositories, e.g., you may have two independent websites
https://username.github.io/proj-b/, corresponding to GitHub repositories
username/proj-b, respectively. However, since you can connect any GitHub repositories with Netlify, and each repository can be associated with a domain or subdomain name, you may replace GitHub Project Pages with different subdomains like
proj-b.netlify.com. The actual limitation is that you cannot use subpaths in the URL but you can use any (sub)domain names.
Although GitHub does not officially support Hugo (only Jekyll is supported), you can actually publish any static HTML files on GitHub Pages, even if they are not built with Jekyll. The first requirement for using GitHub Pages is that you have to create a GitHub repository named
username.github.io under your account (replace
username with your actual GitHub username), and what’s left is to push your website files to this repository. The comprehensive documentation of GitHub Pages is at https://pages.github.com, and please ignore anything related to Jekyll there unless you actually use Jekyll instead of Hugo. To make sure GitHub does not rebuild your website using Jekyll and just publish whatever files you push to the repository, you need to create a (hidden) file named
.nojekyll in the repository.39 GitHub offers a free subdomain
username.github.io, and you can use your own domain name by configuring its A or CNAME records to point it to GitHub Pages (consult the GitHub Pages documentation for instructions).
public/ directory should be the GIT repository. You have two possible choices for setting up this repository locally. The first choice is to follow the default structure of a Hugo website like the diagram below, and initialize the GIT repository under the
Publish R Markdown On Github Free
If you know how to use the command line, change the working directory to
public/, and initialize the GIT repository there:
The other choice is to clone the GitHub repository you created to the same directory as your website source:
And the structure looks like this:
Publish R Markdown On Github
The source directory and the
username.github.io directory are under the same parent directory. In this case, you need to set the option
publishDir = '../username.github.io' in