gov-uk-rap-materials_git-going-with-R.Rmd

---
title: "`git` going with R"
author: "Joseph Crispell"
date: "`r format(Sys.Date(), '%d %b %Y')`"
output:
  ioslides_presentation:
    logo: images/logos/DataScienceCampus_logo_square.png
    widescreen: true
    css: 
      css/custom.css
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)
```

```{r load required libraries, include=FALSE}
library(kableExtra) # Extra nice tables
```

<!-- Extra custom code to add "OFFICIAL" into the header -->

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.2/jquery.min.js"></script>

<script>
    $(document).ready(function() {
      $('slide:not(.title-slide, .backdrop, .segue)').append('<header label=\"OFFICIAL\"></header>');    
    })
</script>

<style>
  header:after {
    content: attr(label);
    font-size: 12pt;
    position: absolute;
    top: 10px;
    left: 10px;
    line-height: 1.9;
  }
</style>

<!-- END custom code block for header -->

<!-- Extra custom code for footnotes - taken from https://stackoverflow.com/questions/42690955/how-to-insert-footnotes-in-ioslides-presentations-using-rmarkdown -->

<!-- PRESENTER NOTES
To view notes press "p" during the presentation on each slides with notes and an element with notes inside will appear. 

Note that you can use presenter mode by adding "presentme=true" to presentation url ("my-presentation.html?presentme=true"). Turn off presenter mode by adding "?presentme=false" to the url.

More information on "ioslides" available here: https://bookdown.org/yihui/rmarkdown/ioslides-presentation.html.
-->

## What is git?

"You use Git to take snapshots of all the files in a folder."

[_Alice Bartlett_](https://speakerdeck.com/alicebartlett/git-for-humans)

<br>

<p class="aligncenter">
    <img src="images/SnapshotOfFolder.png" width="60%" height="auto">
</p>

<div class="notes">
  git is a version control tool. It is a way of keeping track of:
  
  - How are files are changing
  - Who is making those changes
  - When were the changes made
  - Why were the changes made
</div>

## Snapshots in time

<p class="aligncenter">
    <img src="images/FileVersionControl.png" width="100%" height="auto">
</p>

<div class="notes">
  On the left, we have a typical file version tracking systems. We create new files and include dates and flags to denote changes that were made. With this we quickly lose track of different versions of our files and we end up with a cluttered file system.
  
  On the right, we have the same file but monitored by git. It remains a single file throughout but git has recorded how, when, why and who has made what changes to the document. We can easily track back through how the document has changed.
</div>

## Three key concepts

<img src="images/VersionControl_vertical.png" width="15%" height="auto" align="right">

<br>

- **Repository** - your project folder
- **Commit** - a snapshot of your folder
  * We use `push` to send the snapshots online
  * And `pull` to retrieve an updated snapshot
- **Branch** - a working version of your folder

<div class="notes">
  There are three key concepts to version control:

  1. Repository - this is the same as a folder on our computer. It's the place we keep all teh files we need for a particular project.
  2. Commit - this is how we tell git that we have made some changes we'd like it to record
  3. Branch - we can think of branches as a copy of our folder that we are currently working on for a particular task. Once we have completed the work we'll merge any changes back into the main copy of the repository.
  
  Alongside commit we have push and pull that allow us to push changes into our repository and pull changes from an updated version of the repository.
</div>

## Work `git`!

<p class="aligncenter">
    <img src="images/WorkingWithGit/WorkingWithGit_13.png" width="100%" height="auto">
</p>

<div class="notes">
  Here's an example of a repository - a set of files underpinning a project.
  
  The repository changes through time with checkpoints (circles) representing changes that have been recorded. 
  
  The repository also branches, with different branches representing different pieces of work.
  
  In this case, the example repository is the repository that we use to store teaching materials we develop.
</div>

## Installing `git`

<img src="images/logos/git_logo.png" width="40%" height="auto" align="right">

<br>

- For Windows, download the executable [here](https://git-scm.com/download/win)
- On a mac type `git --version` in your terminal
- On linux machines type `sudo apt install git-all` in your terminal

<br>

_Note that you may need admin rights on your computer, without these you'll need to request an install._

<div class="notes">
  To get started with git, you'll need to install it on your computer following these instructions.
</div>

## Create a GitHub account

<img src="images/logos/github_logo_octo.png" width="35%" height="auto" align="right">

<br>

GitHub offers a range of account types. A free account is available for organisations and individuals.

Even if you're in an institution, create a personal GitHub account to keep track of you own work.

You'll find more information, and links for creating an account, [here](https://help.github.com/en/github/getting-started-with-github/signing-up-for-a-new-github-account).

<div class="notes">
  Next, you'll need to create a GitHub account - GitHub is the tool to interact with the git version control system. It is an incerdible open-source resources that is used by millions of people around the world to manage and record code development.
</div>

## Create a repository

- Follow the instructions [here](https://help.github.com/en/enterprise/2.16/user/github/getting-started-with-github/create-a-repo) to create your first repository
- Some key files to include:

  `README` - ideally format this as a markdown `md` file (more info [here](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes) and [here](https://github.com/18F/open-source-guide/blob/18f-pages/pages/making-readmes-readable.md))<br>
  
  `LICENSE` - how you want people to re-use your code ([info](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/licensing-a-repository))<br>
  
  `.gitignore` - names of any files in your project you don't want on GitHub ([templates](https://github.com/github/gitignore/blob/master/README.md))<br>
  
<p class="aligncenter">
    <img src="images/VersionControl_withoutGitLogo.png" width="75%" height="auto">
</p>

<div class="notes">
  Next we need to create a repository - a folder that we are going to use to store the files we need for a particular project.
  
  The repository has some key files:
  
  - The README.md - tells you and others about the project
  - The LICENCE - tells others how they can use your code and acknowledge your work
  - .gitignore - a file that allows us to target specific files that we don't want to track changes of - for example sensitive data files
</div>

## Linking to RStudio

<img src="images/logos/RStudio_logo.png" width="35%" height="auto" align="right">

<br><br>

- Rstudio does a lot of the hard work for you
- You can use the terminal, if you like
- Here are some screenshots showing you how to link a GitHub repository to RStudio

<div class="notes">
  With git installed, a GitHub account and repository created. We can use RStudio (the Interactive Development Environment (IDE) designed to help us create R code to make a local copy of our repository and begin our project.
  
  The following screenshots illustrate how to use RStudio to get started using git to track your work in a repository.
</div>

## {data-background=images/RStudioAndGit/RStudioAndGit_1.png data-background-size=100%}
<div class="notes">
  Start by navigating to your repository on GitHub using the browser.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_2.png data-background-size=100%}
<div class="notes">
  Click on the green "Code" button and copy the url under HTTPS.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_4.png data-background-size=100%}
<div class="notes">
  Now open up RStudio - don't worry that mine is dark - I do that to make me look like a real programmer!
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_5.png data-background-size=100%}
<div class="notes">
  Select file and new project.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_6.png data-background-size=100%}
<div class="notes">
  Select version control.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_7.png data-background-size=100%}
<div class="notes">
  Select git.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_9.png data-background-size=100%}
<div class="notes">
  Paste the repository url in here.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_10.png data-background-size=100%}
<div class="notes">
  The repository name should autofill but if not enter the name of your repository.
  
  Select where on your compter you want to store your repository.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_11.png data-background-size=100%}
<div class="notes">
  Now it should copy all the repository contents onto your local computer.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_12.png data-background-size=100%}
<div class="notes">
  And that's the copy complete. You can see the copied files in the bottom right corner. Note that I have create a copy of the RAP meterials repository.
  
  Now you can begin working on the files in RStudio.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_13.png data-background-size=100%}
<div class="notes">
  Next I selected the README.md file.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_14.png data-background-size=100%}
<div class="notes">
  I added some additional text to explain how to view presenter notes for the presentations.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_15.png data-background-size=100%}
<div class="notes">
  I then open the Git tab in the top right corner.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_16.png data-background-size=100%}
<div class="notes">
  Clicked the checkbox to stage the changes I made to the README file.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_17.png data-background-size=100%}
<div class="notes">
  Then clicked commit.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_18.png data-background-size=100%}
<div class="notes">
  And added a message into commit message box detailing the changes I made.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_19.png data-background-size=100%}
<div class="notes">
  And clicked commit.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_20.png data-background-size=100%}
<div class="notes">
  I closed the terminal once finished and then clicked push in the top right corner.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_21.png data-background-size=100%}
<div class="notes">
  I then navigated to my repository online - notice my commit message has appeared at the top and against the file I changed.
</div>
## {data-background=images/RStudioAndGit/RStudioAndGit_22.png data-background-size=100%}
<div class="notes">
  And if I scroll down to the bottom I can see the changes I made to the README have appeared online. Note that the README is the repository documentation so it will be available to view on the repository site.
</div>

## Useful resources

<img src="images/logos/git_logo.jpg" width="35%" height="auto" align="right">

- Introduction to GitHub presentation ([slides](https://speakerdeck.com/alicebartlett/git-for-humans) and [video](https://www.youtube.com/watch?v=eWxxfttcMts))
- All you need to know about GitHub in their [help](https://help.github.com/en) pages
- Detailed book about git, GitHub and R ([here](https://happygitwithr.com/))
- Detailed overview of RStudio, git and GitHub ([here](http://r-pkgs.had.co.nz/git.html))
- A game to help us think about git branches ([here](https://learngitbranching.js.org/))
- ONS GitHub introductory course ([here](https://github.com/datasciencecampus/version-control-with-git-github))

<div class="notes">
  Here are some useful resources that will help you learn more about git, GitHub, and RStudio.
</div>