09-github.Rmd

# Version control with Git and GitHub {#github_r}

This Chapter will introduce you to the basics of using a version control system to keep track of all your important R code and facilitate collaboration with colleagues and the wider world. This Chapter will focus on using the software 'Git' in combination with the web-based hosting service 'GitHub'. By the end of the Chapter, you will be able to install Git, configure it and connect it to a GitHub account, and setup and work with a version controlled project in RStudio. We won't be covering more advanced topics such as branching, forking and pull requests in much detail but we do give an overview [later](#collab) on in the Chapter.

Just a few notes of caution. In this Chapter we'll be using RStudio to interface with Git as it gives you a nice friendly graphical user interface which generally makes life a little bit easier (and who doesn't want that?). However, one downside to using RStudio with Git is that RStudio only provides pretty basic Git functionality through its menu system. That's fine for most of what we'll be doing during this Chapter (although we will introduce a few Git commands as we go along) but if you really want to benefit from using Git's power you will need to [learn](#resources) some Git commands and syntax. This leads us on to our next point. We're not going to lie, Git can become a little bewildering and frustrating when you first start using it. This is mostly due to the terminology and liberal use of jargon associated with Git, but there's no hiding the fact that it's quite easy to get yourself and your Git repository into a pickle. Therefore, we've tried hard to keep things as straight forward as we can during this Chapter and as a result we do occasionally show you a couple of very 'un-Git' ways of doing things (mostly about reverting to previous versions of documents). Don't get hung up about this, there's no shame to using these low tech solutions and if it works then it works. Lastly, GitHub was not designed to host very large files and will warn you if you try to add files greater than 50 MB and block you adding files greater than 100 MB. If your project involves using large file sizes there are a [few solutions][biggit] but we find the easiest solution is to host these files elsewhere (your institutions network share for example) and create a link to them in a README file or R markdown document on Github.  

## What is version control?

A [Version Control System][version_con] (VCS)  keeps a record of all the changes you make to your files that make up a particular project and allows you to revert to previous versions of files if you need to. To put it another way, if you muck things up or accidentally lose important files you can easily roll back to a previous stage in your project to sort things out. It's a bit like track changes in MS Word, but much more powerful. Version control was originally designed for collaborative software development, but it's equally useful for scientific research and collaborations (although admittedly a lot of the terms, jargon and functionality are focused on the software development side). There are many different version control systems currently available, but we'll focus on using *Git*, because it's free and open source and it integrates nicely with RStudio. This means that its can easily become part of your usual workflow with minimal additional overhead.  

## Why use version control?

So why should you worry about version control? Well, first of all it helps avoid this (familiar?) situation when you're working on a project

\  

```{r youNeedVC1, echo=FALSE, out.width="75%", fig.align="center", fig.cap="You need version control"}
knitr::include_graphics(path = "images/Messy_folder.PNG")
```

\  

usually arising from this (familiar?) scenario

\  

```{r youNeedVC2, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/final_doc.png")
```

\  

Version control automatically takes care of keeping a record of all the versions of a particular file and allows you to revert back to previous versions if you need to. Version control also helps you (especially the future you) keep track of all your files in a single place and it helps others (especially collaborators) review, contribute to and reuse your work through the GitHub [website](https://github.com/). Lastly, your files are always available from anywhere and on any computer, all you need is an internet connection.

## What is Git and GitHub?

**Git** is a version control system originally developed by [Linus Torvalds][linus] that lets you track changes to a set of files. These files can be any type of file including the menagerie of files that typically make up a data orientated project (.pdf, .Rmd, .docx, .txt, .jpg etc) although plain text files work the best (thankfully your .Rmd files are just text files!). All the files that make up a project is called a **repository** (or just **repo**).

**GitHub** is a web-based hosting service for Git repositories which allows you to create a remote copy of your local version-controlled project. This can be used as a backup or archive of your project or make it accessible to you and to your colleagues so you can work collaboratively. 

At the start of a project we typically (but not always) create a **remote** repository on GitHub, then **clone** (think of this as copying) this repository to our **local** computer (the one in front of you). This cloning is usually a one time event and you shouldn't need to clone this repository again unless you really muck things up. Once you have cloned your repository you can then work locally on your project as usual, creating and saving files for your data analysis (scripts, R markdown documents, figures etc). Along the way you can take snapshots (called **commits**) of these files after you've made important changes. We can then **push** these changes to the remote GitHub repository to make a backup or make available to our collaborators. If other people are working on the same project (**repository**), or maybe you're working on a different computer, you can **pull** any changes back to your local repository so everything is synchronised.          

\  

```{r git-cart, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/Github_cartoon2.png")
```

\  

## Getting started {#setup_git}

This Chapter assumes that you have already installed the latest versions of R and RStudio. If you haven't done this yet you can find instructions [here](#install_r).

### Install Git

To get started, you first need to install Git. If you're lucky you may already have Git installed (especially if you have a Linux computer). You can check if you already have Git installed by clicking on the Terminal tab in the Console window in RStudio and typing `git --version` (the space after the `git` command is important). If you see something that looks like `git version 2.25.0` (the version number may be different on your computer) then you already have Git installed (happy days). If you get an error (something like `git: command not found`) this means you don't have Git installed (yet!).


\  

```{r git-version, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/git_version.png")
```

\  

You can also do this check outside RStudio by opening up a separate Terminal if you want. On Windows go to the 'Start menu' and in the search bar (or run box) type `cmd` and press enter. On a Mac go to 'Applications' in Finder, click on the 'Utilities' folder and then on the 'Terminal' program. On a Linux machine simply open the Terminal (Ctrl+Alt+T often does it).  

To install Git on a **Windows** computer we recommend you download and install Git for Windows (also known as 'Git Bash'). You can find the download file and installation instructions [here][git]. 

For those of you using a **Mac** computer we recommend you download Git from [here][git] and install in the usual way (double click on the installer package once downloaded). If you've previously installed Xcode on your Mac and want to use a more up to date version of Git then you will need to follow a few more steps documented [here][git_xcode]. If you've never heard of Xcode then don't worry about it!

For those of you lucky enough to be working on a **Linux** machine you can simply use your OS package manager to install Git from the official repository. For Ubuntu Linux (or variants of) open your Terminal and type

```markup
sudo apt update
sudo apt install git
```

You will need administrative privileges to do this. For other versions of Linux see [here][git-linux] for further installation instructions.  

Whatever version of Git you're installing, once the installation has finished verify that the installation process has been successful by running the command `git --version` in the Terminal tab in RStudio (as described above). On some installations of Git (yes we're looking at you MS Windows) this may still produce an error as you will also need to setup RStudio so it can find the Git executable (described [below](#rs_config)). If you'd like a longer set of installation instructions for your operating system you can find them in [Appendix B](#install_git).

### Configure Git

After installing Git, you need to configure it so you can use it. Git stamps every change you make with a name and an email address, so you need to give Git this information. Happily, you only need to do this once per computer.

There are two ways of going about it. The traditional way is to use the Terminal and we'll show you that in a moment, but as the rest of this Chapter does its best to keep you inside RStudio we'll start with the `usethis`\index{usethis package} package instead. This lets you configure Git from the Console you already know rather than from a command line you may never have opened before. If you don't have `usethis` installed yet then now's the time

```{r usethis-install, eval=FALSE}
install.packages("usethis")
```

and then

```{r usethis-config, eval=FALSE}
library(usethis)

use_git_config(user.name = "Your Name", user.email = "you@youremail.com")
```

substituting `"Your Name"` for your actual name and `"you@youremail.com"` with your email address. We recommend you use your University email address (if you have one) as you will also use this address when you register for your GitHub account (coming up in a bit).  

Whilst you're here there's one more setting worth changing. Every Git repository has a main line of work, which Git calls a **branch**, and this branch needs a name. Git has historically called it `master` whereas GitHub has called it `main` since 2020. If you leave the two disagreeing then sooner or later you'll be rewarded with a baffling error message when you try to push, so let's head that off now

```{r usethis-branch, eval=FALSE}
use_git_config(init.defaultBranch = "main")
```

Every new repository you create from here on will use `main`. This particular setting needs Git 2.28 or newer, which anything you install today will be, but if you're working with an older version of Git then it will quietly ignore you and carry on calling the branch `master`. That's not a disaster and we'll show you how to deal with it in [Option 2](#opt2) below. Don't be surprised to come across both names in the wild either, a lot of repositories were created before the change (including the one this book lives in!).

If you'd rather use the Terminal, or you're simply curious about what `usethis` is doing on your behalf, the equivalent commands are

```
git config --global user.email 'you@youremail.com'

git config --global user.name 'Your Name'

git config --global init.defaultBranch 'main'
```

which you type into the Terminal tab in the Console window. If this was successful, you should see no error messages from these commands.  

Whichever route you took, you can check that it all stuck by asking `usethis` for a situation report

```{r usethis-sitrep1, eval=FALSE}
git_sitrep()
```

`git_sitrep()`\index{git\_sitrep()} summarises your entire Git and GitHub setup in one go and we'll return to it in a bit once you have a GitHub account for it to check as well. For now, all you're looking for is your name and email address near the top of the output. The Terminal equivalent is `git config --global --list`.

### Configure RStudio {#rs_config}

As you can see above, Git can be used from the command line, but it also integrates well with RStudio, providing a friendly graphical user interface. If you want to use RStudio's Git integration (we recommend you do - at least at the start), you need to check that the path to the Git executable is specified correctly. In RStudio, go to the menu `Tools` -> `Global Options` -> `Git/SVN` and make sure that 'Enable version control interface for RStudio projects' is ticked and that the 'Git executable:' path is correct for your installation. If it's not correct hit the `Browse...` button and navigate to where you installed git and click on the executable file. You will need to restart RStudio after doing this.

\  

```{r git-rs, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/git_path.png")
```

### Register a GitHub account

If all you want to do is to keep track of files and file versions on your local computer then Git is sufficient. If however, you would like to make an off-site copy of your project or make it available to your collaborators then you'll need a web-based hosting service for your Git repositories. This is where GitHub comes into play (there are also other services like [GitLab][gitlab], [Bitbucket][bitbucket] and [Savannah][savannah]). You can sign up for a free account on GitHub [here][git_join]. You will need to specify a username, an email address and a strong password. We suggest that you use your University email address (if you have one) as this will also allow you to apply for a free [educator or researcher account][git_edu] later on which gives you some useful [benefits][git-ben] (don't worry about this now though, GitHub is still free without it). When it comes to choosing a username we suggest you give this some thought. Choose a short(ish) rather than a long username, use all lowercase and hyphenate if you want to include multiple words, find a way of incorporating your actual name and lastly, choose a username that you will feel comfortable revealing to your current/future employer!  

You may be asked to solve a simple puzzle to prove you're human, after which GitHub will email you a verification code to type in. There's no plan to choose, as a personal account is free and comes with everything we need.  

Whilst you're setting up your account it's worth thinking about turning on two-factor authentication (2FA). This is where GitHub asks for a short code from an app on your phone as well as your password whenever you log in, and it makes your account a great deal harder for somebody else to get into. It takes about five minutes to set up with an authenticator app. GitHub only *insists* on 2FA for accounts which meet certain contributor criteria (publishing an app or an action, creating a release, contributing to particularly widely used repositories and so on) so you almost certainly won't be required to use it for anything we do in this Chapter. We'd still recommend it though. You can find GitHub's own instructions [here][git-2fa] and you can always come back and switch it on later if you'd rather press on for now.  

Once you've completed all those steps you'll have both Git and GitHub set up. There's one last piece of the puzzle to slot into place before the two of them will actually talk to each other though, which is what the next section is all about.

### Authenticate with GitHub {#github-auth}

At some point fairly soon you're going to ask Git to send your work up to GitHub, and when you do, GitHub is going to want to know that you are who you say you are. You might expect to type in the password you chose in the previous section. You can't. GitHub stopped accepting account passwords for this in August 2021 and if you try it you'll be met with an authentication error which does a particularily poor job of explaining what's actually wrong.  

What you use instead is a **personal access token**\index{personal access token} (PAT), which is a long string of random looking characters that acts as a password for a single computer. Tokens are rather better than passwords for this job. You can have a different one for each machine you work on, you can give each one a limited lifespan, and if one of them ever goes astray you can cancel it on its own without touching your password or any of your other computers.  

You could create a token by digging through your GitHub account settings, but the `usethis` package will do the digging for you

```{r pat-create, eval=FALSE}
create_github_token()
```

This opens GitHub in your web browser on the token creation page with all of the permissions you need already ticked. The page is headed 'New personal access token (classic)'. You may notice that GitHub also offers a newer sort of token called a fine-grained token in the sidebar, but classic tokens are simpler to set up and are what `usethis` prepares for you, so stick with those for now. Before you click the green 'Generate token' button at the bottom there are two things you should change.  

The first is the **Note**, which is just a label to help you remember which computer this token belongs to. `usethis` fills in something generic, so replace it with something that will still mean something to you in six months time (`work laptop` for example).  

The second is the **Expiration**. GitHub suggests 30 days, which is a great security practice but does mean your token will stop working disappointingly soon. Click the dropdown and pick something that suits how you work. If you're using this book as part of a taught course then we'd suggest choosing 'Custom' and setting a date comfortably beyond the end of it, so your token doesn't expire in the middle of writing up. Whatever you choose, you're making a trade between security and convenience and it's worth doing that deliberately rather than by accident.  

<!-- Screenshot slot: drop images/git_pat_form.png into images/ and this renders automatically. Token form with the Note field and the Expiration dropdown both visible, dropdown open on Custom. -->

\  

```{r git-pat1, echo=FALSE, out.width="85%", fig.align="center", eval=file.exists("images/git_pat_form.png")}
knitr::include_graphics(path = "images/git_pat_form.png")
```

\  

Now click 'Generate token'. GitHub will show you the token on a green background, and this is the only time it will ever do so. Copy it now. If you navigate away from that page without copying it then there's no way of getting it back and you'll simply have to generate another one, which is irritating but harmless.  

<!-- Screenshot slot: drop images/git_pat_token.png into images/ and this renders automatically. The generated token on its green background with the copy icon. Token must be blurred or fake. -->

\  

```{r git-pat2, echo=FALSE, out.width="80%", fig.align="center", eval=file.exists("images/git_pat_token.png")}
knitr::include_graphics(path = "images/git_pat_token.png")
```

\  

The last thing to do is hand the token over to your computer's credential store so that you never have to type it again. In your Rstudio console

```{r pat-store, eval=FALSE}
library(usethis)
gitcreds::gitcreds_set()
```

Paste the token that you have just copied in when you're prompted and press enter. That's it. Git will now find the token by itself every time it needs it and you can go back to forgetting that any of this exists. (You won't need to install `gitcreds`\index{gitcreds package} separately, by the way, as `usethis` brings it along with it.)  

<!-- Screenshot slot: drop images/git_pat_store.png into images/ and this renders automatically. The Console after gitcreds::gitcreds_set(), showing the prompt asking for the token. -->

```{r git-pat3, echo=FALSE, out.width="60%", fig.align="center", eval=file.exists("images/git_pat_store.png")}
knitr::include_graphics(path = "images/git_pat_store.png")
```

Now's a good time to run the situation report again, as this time there's more for it to tell you

```{r usethis-sitrep2, eval=FALSE}
git_sitrep()
```

Read the output even though nothing has gone wrong. Knowing what a healthy setup looks like is what makes `git_sitrep()` useful. The lines to check are your name and email address, and a line further down confirming that a personal access token was found.  

<!-- Screenshot slot: drop images/git_sitrep.png into images/ and this renders automatically. A healthy git_sitrep() output with the email address redacted. -->

\  

```{r git-sitrep, echo=FALSE, out.width="75%", fig.align="center", eval=file.exists("images/git_sitrep.png")}
knitr::include_graphics(path = "images/git_sitrep.png")
```

\  

Finally, a word about what happens when your token expires, because it will at some point. The symptom is that pushing and pulling, which worked perfectly well previously, suddenly starts failing with a message about authentication. The fix is simply to do it all again

```{r pat-renew, eval=FALSE}
create_github_token()      # generate a shiny new one
gitcreds::gitcreds_set()   # it'll offer to replace the old one, say yes
git_sitrep()               # check it worked
```

Your work is safely on your computer and on GitHub throughout, so an expired token is a five minute annoyance rather than a disaster. If you'd like a good deal more detail on any of this then the [personal access token][happy-pat] chapter of Jenny Bryan's [Happy Git and GitHub][git_happy] is the place to go, and GitHub's own documentation on [managing your tokens][git-pat] is worth a look too.

## Setting up a project in RStudio

Now that you're all set up, let's create your first version controlled RStudio project. There are a couple of different approaches you can use to do this. You can either setup a remote GitHub repository first then connect an RStudio project to this repository (we'll call this Option 1). Another option is to setup a local repository first and then link a remote GitHub repository to this repository (Option 2). You can also connect an existing project to a GitHub repository but we won't cover this here. We suggest that if you're completely new to Git and GitHub then use Option 1 as this approach sets up your local Git repository nicely and you can **push** and **pull** immediately. Option 2 requires a little more work and therefore there are more opportunities to go wrong. We will cover both of these options below. 

### Option 1 - GitHub first {#opt1}

To use the GitHub first approach you will first need to create a **repository (repo)** on GitHub. Go to your [GitHub page][github] and sign in if necessary. Click on the 'Repositories' tab at the top and then on the green 'New' button on the right (the `+` icon in the top right corner of any GitHub page and then 'New repository' gets you to the same place) 

\  

```{r new-repo1, echo=FALSE, out.width="85%", fig.align="center"}
knitr::include_graphics(path = "images/new_repo.png")
```

\  

Give your new repo a name (let's call it `first_repo` for this Chapter) in the 'General' section at the top. Underneath, in the 'Configuration' section, leave 'Choose visibility' set to 'Public' and switch the 'Add README' toggle to 'On' (this is important). Ignore the '.gitignore' and 'license' options for now and click on the green 'Create repository' button. 

\  

```{r new-repo2, echo=FALSE, out.width="55%", fig.align="center"}
knitr::include_graphics(path = "images/new_repo_opt.png")
```

\  

Your new GitHub repository will now be created. Notice the README has been rendered in GitHub and is in markdown (.md) format (see [Chapter 8](#rmarkdown_r) on R markdown if this doesn't mean anything to you). Next click on the green 'Code' button, make sure the 'HTTPS' tab is selected and copy the `https://...` URL that pops up for later (either highlight it all and copy or click on the copy to clipboard icon to the right). The URL will end in `.git`.

\  

```{r new-repo3, echo=FALSE, out.width="80%", fig.align="center"}
knitr::include_graphics(path = "images/new_repo_clone.png")
```

\  

Ok, we now switch our attention to RStudio. In RStudio click on the `File` -> `New Project` menu. In the pop up window select `Version Control`.

\  

```{r new-proj1, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/proj_setup1.png")
```

\  

Now paste the URL you previously copied from GitHub into the `Repository URL:` box. This should then automatically fill out the `Project Directory Name:` section with the correct repository name (it's important that the name of this directory has the same name as the repository you created in GitHub). You can then select where you want to create this directory by clicking on the `Browse` button opposite the `Create project as a subdirectory of:` option. Navigate to where you want the directory created on your computer and click OK. We also like to tick the `Open in new session` option. 

\  

```{r new-proj2, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/proj_setup2.png")
```

\  

RStudio will now create a new directory with the same name as your repository on your local computer and will then **clone** your remote repository to this directory. The directory will contain three new files; `first_repo.Rproj` (or whatever you called your repository), `README.md` and `.gitignore`. You can check this out in the `Files` tab usually in the bottom right pane in RStudio. You will also have a `Git` tab in the top right pane with two files listed (we will come to this later on in the Chapter). That's it for Option 1, you now have a remote GitHub repository set up and this is linked to your local repository managed by RStudio. Any changes you make to files in this directory will be version controlled by Git and you can push these changes to GitHub.

\  

```{r new-proj2a, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/proj_setup3.png")
```

### Option 2 - RStudio first {#opt2}

An alternative approach is to create a local RStudio project first and then link to a remote Github repository. As we mentioned before, this option is more involved than Option 1 so feel free to skip this now and come back later to it if you're interested. This option is also useful if you just want to create a local RStudio project linked to a local Git repository (i.e. no GitHub involved). If you want to do this then just follow the instructions below omitting the GitHub bit.

\  

In RStudio click on the `File` -> `New Project` menu and select the `New Directory` option.

\  

```{r new-proj3, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS1.png")
```

\  

In the pop up window select the `New Project` option

\  

```{r new-proj4, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/proj_setup_RS.png")
```

\ 

In the New Project window specify a `Directory name` (choose `second_repo` for this Chapter) and select where you would like to create this directory on you computer (click the `Browse` button). Make sure the `Create a git repository` option is ticked. 

\  

```{r new-proj5, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS2.png")
```

\  

This will create a version controlled directory called `second_repo` on your computer that contains two files, `second_repo.Rproj` and `.gitignore` (there might also be a `.Rhistory` file but ignore this). You can check this by looking in the `Files` tab in RStudio (usually in the bottom right pane).  

\  

```{r new-proj6, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS3.png")
```

\  

OK, before we go on to create a repository on GitHub we need to do one more thing - we need to place our `second_repo.Rproj` and `.gitignore`files under version control. Unfortunately we haven't covered this in detail yet so just follow the next few instructions (blindly!) and we'll revisit them in the [Using Git](#use_git) section of this Chapter.  

To get our two files under version control click on the 'Git' tab which is usually in the top tight pane in RStudio.

\  

```{r new-proj7, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS4.png")
```

\  

You can see that both files are listed. Next, tick the boxes under the 'Staged' column for both files and then click on the 'Commit' button. 

\  

```{r new-proj8, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS5.png")
```

\  

This will take you to the 'Review Changes' window. Type in the commit message 'First commit' in the 'Commit message' window and click on the 'Commit' button. A new window will appear with some messages which you can ignore for now. Click 'Close' to close this window and also close the 'Review Changes' window. The two files should now have disappeared from the Git pane in RStudio indicating a successful commit. 

\  

```{r new-proj9, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS6.png")
```

\  

OK, that's those two files now under version control. Now we need to create a new repository on GitHub. In your browser go to your [GitHub page][github] and sign in if necessary. Click on the 'Repositories' tab and then click on the green 'New' button on the right. Give your new repo the name `second_repo` (the same as your version controlled directory name) and leave 'Choose visibility' set to 'Public'. This time leave the 'Add README' toggle switched **off** (this is important) and then click on 'Create repository'. 

\  


```{r new-proj10, echo=FALSE, out.width="55%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS7.png")
```

\  

This will take you to a Quick setup page which provides you with some code for various situations. The code we are interested in is the code under `...or push an existing repository from the command line` heading.  

\  

```{r new-proj11, echo=FALSE, out.width="65%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS8.png")
```

\  

Highlight and copy the first line of code (note: yours will be slightly different as it will include your GitHub username not mine)  

`git remote add origin https://github.com/alexd106/second_repo.git`  

Switch to RStudio, click on the 'Terminal' tab in the Console pane and paste the command into the Terminal. This simply tells your local repository where its remote counterpart lives. Now go back to GitHub and copy the second line  

`git branch -M main`  

which renames your local branch to `main` so that it matches the name GitHub is expecting. If you set `init.defaultBranch` back in [Section 9.4.2](#configure-git) then your branch is probably called `main` already and this command will do nothing at all, which is exactly what we want. If you didn't, or your version of Git was too old to take any notice, then this is the command that puts things right. Paste it into the Terminal and then copy the third and final line  

`git push -u origin main`  

and paste this into the Terminal in RStudio too. You should see something like this

\  

```{r new-proj12, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS9.png")
```

\  

If you take a look at your repo back on GitHub (click on the `second_repo` link at the top) you will see the `second_repo.Rproj` and `.gitignore` files have now been **pushed** to GitHub from your local repository.

\  

```{r new-proj13, echo=FALSE, out.width="75%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS10.png")
```

\  

The last thing we need to do is create and add a **README** file to your repository. A README file describes your project and is written using the same Markdown language you learned in the R markdown [Chapter](#rmarkdown_r). A good README file makes it easy for others (or the future you!) to use your code and reproduce your project. You can create a README file in RStudio or in GitHub. Let's use the second option.  

In your repository on GitHub scroll down to the 'README' panel underneath the list of files and click on the green `Add a README` button. 

\  

```{r new-proj14, echo=FALSE, out.width="75%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS11.png")
```

\  

This opens up GitHub's file editor with your new file already named `README.md` for you. Make sure the `Edit` tab is selected (rather than `Preview`), write a short description of your project and then click on the green `Commit changes...` button in the top right. 

\  

```{r new-proj15, echo=FALSE, out.width="100%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS12.png")
```

\  

This doesn't commit your file straight away. Instead a 'Commit changes' window pops up to let you describe what you've done, in exactly the same way you would in RStudio. GitHub helpfully suggests a commit message for you, which you're can replace with one of your own (we'll have more to say about writing useful commit messages [later](#use_git)). You can ignore the 'Extended description' box. Make sure 'Commit directly to the `main` branch' is selected and then click on the green 'Commit changes' button to finish.

\  

```{r new-proj15a, echo=FALSE, out.width="40%", fig.align="center"}
knitr::include_graphics(path = "images/new_proj_RS13.png")
```

\  

You should now see the `README.md` file listed in your repository. It won't actually exist on your computer yet as you will need to **pull** these changes back to your local repository, but more about that in the next section.  

\  

Whether you followed Option 1 or Option 2 (or both) you have now successfully setup a version controlled RStudio project (and associated directory) and linked this to a GitHub repository. Git will now monitor this directory for any changes you make to files and also if you add or delete files. If the steps above seem like a bit of an ordeal, just remember, you only need to do this once for each project and it gets much easier over time. 

## Using Git {#use_git}

Now that we have our project and repositories (both local and remote) set up, it's finally time to learn how to use Git in RStudio!  

Typically, when using Git your workflow will go something like this:   

1. You create/delete and edit files in your project directory on your computer as usual (saving these changes as you go)  

2. Once you've reached a natural 'break point' in your progress (i.e. you'd be sad if you lost this progress) you **stage** these files

3. You then **commit** the changes you made to these staged files (along with a useful commit message) which creates a permanent snapshot of these changes  

4. You keep on with this cycle until you get to a point when you would like to **push** these changes to GitHub  

5. If you're working with other people on the same project you may also need to **pull** their changes to your local computer  

```{r workflow, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/workflow_3.png")
```

\  

OK, let's go through an example to help clarify this workflow. In RStudio open up the `first_repo.Rproj` project you created previously during Option 1. Either use the `File` -> `Open Project` menu or click on the top right project icon and select the appropriate project. 

\  

```{r rm0, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd0.png")
```

\  

Create an R markdown document inside this project by clicking on the `File` -> `New File` -> `R markdown` menu (remember from the R markdown [Chapter](#rmarkdown_r)?). If you haven't had a chance to look through the R markdown Chapter then just create an R script (.R) or even a text file (.txt) or just blindly follow the instructions below. 

Once created, we can delete all the example R markdown code (except the YAML header) as usual and write some interesting R markdown text and include a plot. We'll use the inbuilt `cars` dataset to do this. Save this file (cmd + s for Mac or ctrl + s in Windows). Your R markdown document should look something like the following (it doesn't matter if it's not exactly the same).

\  

```{r rm1, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd.png")
```

\  

Take a look at the 'Git' tab (top right in RStudio) which should list your new R markdown document (`first_doc.Rmd` in this example) along with `first_repo.Rproj`, and `.gitignore` (you created these files previously when following Option 1).

\  

```{r rm2, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd2.png")
```

\  

Following our workflow, we now need to **stage** these files. To do this tick the boxes under the 'Staged' column for all files. Notice that there is a status icon next to the box which gives you an indication of how the files were changed. In our case all of the files are to be added (capital A) as we have just created them.

\  

```{r rm3, echo=FALSE, out.width="15%", fig.align="center"}
knitr::include_graphics(path = "images/rstudio_git_cols.png")
```

\  

After you have staged the files the next step is to **commit** the files. This is done by clicking on the 'Commit' button.

\  

```{r rm4, echo=FALSE, out.width="50%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd3.png")
```

\  

After clicking on the 'Commit' button you will be taken to the 'Review Changes' window. You should see the three files you staged from the previous step in the left pane. If you click on the file name `first_doc.Rmd` you will see the changes you have made to this file highlighted in the bottom pane. Any content that you have added is highlighted in green and deleted content is highlighted in red. As you have only just created this file, all the content is highlighted in green. To commit these files (take a snapshot) first enter a mandatory commit message in the 'Commit message' box. This message should be relatively short and informative (to you and your collaborators) and indicate why you made the changes, not what you changed. This makes sense as Git keeps track of *what* has changed and so it is best not to use commit messages for this purpose. It's traditional to enter the message 'First commit' (or 'Initial commit') when you commit files for the first time. Now click on the 'Commit' button to commit these changes.

\  

```{r rm5, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd4.png")
```

\  

A summary of the commit you just performed will be shown. Now click on the 'Close' button to return to the 'Review Changes' window. Note that the staged files have now been removed.

\  

```{r rm6, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd5.png")
```

\  

Now that you have committed your changes the next step is to **push** these changes to GitHub. Before you push your changes it's good practice to first **pull** any changes from GitHub. This is especially important if both you and your collaborators are working on the same files as it keeps you local copy up to date and avoids any potential conflicts. In this case your repository will already be up to date but it's a good habit to get into. To do this, click on the 'Pull' button on the top right of the 'Review Changes' window. Once you have pulled any changes click on the green 'Push' button to push your changes. You will see a summary of the push you just performed. Hit the 'Close' button and then close the 'Review Changes' window. 

\  
```{r rm7, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd6.png")
```

\  

To confirm the changes you made to the project have been pushed to GitHub, open your GitHub page, click on the Repositories link and then click on the  `first_repo` repository. You should see four files listed including the `first_doc.Rmd` you just pushed. Along side the file name you will see your last commit message ('First commit' in this case) and when you made the last commit.

\  

```{r rm8, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd7.png")
```

\  

To see the contents of the file click on the `first_doc.Rmd` file name.

\  

```{r rm9, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/first_Rmd8.png")
```

### Tracking changes 

After following the steps outlined above, you will have successfully modified an RStudio project by creating a new R markdown document, staged and then committed these changes and finally pushed the changes to your GitHub repository. Now let's make some further changes to your R markdown file and follow the workflow once again but this time we'll take a look at how to identify changes made to files, examine the commit history and how to restore to a previous version of the document.  

In RStudio open up the `first_repo.Rproj` file you created previously (if not already open) then open the `first_doc.Rmd` file (click on the file name in the `Files` tab in RStudio).  

Let's make some changes to this document. Delete the line beginning with 'My first version controlled ...' and replace it with something more informative (see figure below). We will also change the plotted symbols to red and give the plot axes labels. Lastly, let's add a summary table of the dataframe using the `kable()`\index{kable()} and `summary()`\index{summary()} functions (you may need to install the `knitr`\index{knitr package} package if you haven't done so previously to use the `kable()` function) and finally render this document to pdf by changing the YAML option to `output: pdf_document`.

\  

```{r mod1, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/mod1.png")
```

\  

Now save these changes and then click the `knit` button to render to pdf. A new pdf file named `first_doc.pdf` will be created which you can view by clicking on the file name in the `Files` tab in RStudio.  

Notice that these two files have been added to the `Git` tab in RStudio. The status icons indicate that the `first_doc.Rmd` file has been modified (capital M) and the `first_doc.pdf` file is currently untracked (question mark).

\  

```{r mod2, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/mod2.png")
```

\  

To stage these files tick the 'Staged' box for each file and click on the 'Commit' button to take you to the 'Review Changes' window.

\  

```{r mod3, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/mod3.png")
```

\  

Before you commit your changes notice the status of `first_doc.pdf` has changed from untracked to added (A). You can view the changes you have made to the `first_doc.Rmd` by clicking on the file name in the top left pane which will provide you with a useful summary of the changes in the bottom pane (technically called diffs). Lines that have been deleted are highlighted in red and lines that have been added are highlighted in green (note that from Git's point of view, a modification to a line is actually two operations: the removal of the original line followed by the creation of a new line). Once you're happy, commit these changes by writing a suitable commit message and click on the 'Commit' button.

\  

```{r mod4, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/mod4.png")
```

\  

To push the changes to GitHub, click on the 'Pull' button first (remember this is good practice even though you are only collaborating with yourself at the moment) and then click on the 'Push' button. Go to your online GitHub repository and you will see your new commits, including the `first_doc.pdf` file you created when you rendered your R markdown document. 
 
\  

```{r mod5, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/mod5.png")
```

\  

To view the changes in `first_doc.Rmd` click on the file name for this file.

\  

```{r mod6, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/mod6.png")
```

### Commit history 

One of the great things about Git and GitHub is that you can view the history of all the commits you have made along with the associated commit messages. You can do this locally using RStudio (or the Git command line) or if you have pushed your commits to GitHub you can check them out on the GitHub website.  

To view your commit history in RStudio click on the 'History' button (the one that looks like a clock) in the Git pane to bring up the history view in the 'Review Changes' window. You can also click on the 'Commit' or 'Diff' buttons which takes you to the same window (you just need to additionally click on the 'History' button in the 'Review Changes' window).  

\ 

```{r his1, echo=FALSE, out.width="60%", fig.align="center"}
knitr::include_graphics(path = "images/c_history.png")
```

\  

The history window is split into two parts. The top pane lists every commit you have made in this repository (with associated commit messages) starting with the most recent one at the top and oldest at the bottom. You can click on each of these commits and the bottom pane shows you the changes you have made along with a summary of the **Date** the commit was made, **Author** of the commit and the commit message (**Subject**). There is also a unique identifier for the commit (**SHA** - Secure Hash Algorithm) and a **Parent** SHA which identifies the previous commit. These SHA identifiers are really important as you can use them to view and revert to previous versions of files (details [below](#undo)). You can also view the contents of each file by clicking on the 'View file @ SHA key' link (in our case 'View file @ 2b4693d1').  

\  

```{r his2, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/c_history2.png")
```

\  

You can also view your commit history on GitHub website but this will be limited to only those commits you have already pushed to GitHub. To view the commit history navigate to the repository and click on the 'commits' link (in our case the link will be labelled '3 commits' as we have made 3 commits).

\  

```{r his3, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/c_history3.png")
```

\  

You will see a list of all the commits you have made, along with commit messages, date of commit and the SHA identifier (these are the same SHA identifiers you saw in the RStudio history). You can even browse the repository at a particular point in time by clicking on the `<>` link. To view the changes in files associated with the commit simply click on the relevant commit link in the list.

\  

```{r his4, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/c_history4.png")
```

\  

Which will display changes using the usual format of green for additions and red for deletions.

\  

```{r his5, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/c_history5.png")
```

### Reverting changes {#undo}

One of the great things about using Git is that you are able to revert to previous versions of files if you've made a mistake, broken something or just prefer an earlier approach. How you do this will depend on whether the changes you want to discard have been staged, committed or pushed to GitHub. We'll go through some common scenarios below.  

This is also the point at which RStudio's Git pane starts to run out of road. The first couple of scenarios below can be dealt with entirely by pointing and clicking, but the further back into your history you want to reach the more likely it is that we'll have to drop into the Terminal, for the simple reason that RStudio doesn't give you a button for it. We're not being purists here and there's nothing to be nervous about, it's just that the graphical interface only ever covered the everyday cases. The Terminal tab sits right next to the Console in RStudio so you won't have to go anywhere to use it.  

#### Changes saved but not staged, committed or pushed {-}

If you have saved changes to your file(s) but not staged, committed or pushed these files to GitHub you can right click on the offending file in the Git pane and select 'Revert ...'. This will roll back all of the changes you have made to the same state as your last commit. Just be aware that you cannot undo this operation so use with caution. 

\  

```{r rev1, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert1.png")
```

\  

You can also undo changes to just part of a file by opening up the 'Diff' window (click on the 'Diff' button in the Git pane). Select the line you wish to discard by double clicking on the line and then click on the 'Discard line' button. In a similar fashion you can discard chunks of code by clicking on the 'Discard chunk' button.  

\  

```{r rev2, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert2.png")
```

#### Staged but not committed and not pushed {-}

If you have staged your files, but not committed them then simply unstage them by clicking on the 'Staged' check box in the Git pane (or in the 'Review Changes' window) to remove the tick. You can then revert all or parts of the file as described in the section above. 

#### Staged and committed but not pushed {-}

If you have made a mistake or have forgotten to include a file in your last commit which you have not yet pushed to GitHub, you can just fix your mistake, save your changes, and then amend your previous commit. You can do this by staging your file and then tick the 'Amend previous commit' box in the 'Review Changes' window before committing.   

\  

```{r rev3, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert3.png")
```

\  

If we check out our commit history you can see that our latest commit contains both changes to the file rather than having two separate commits. We use the amend commit approach alot but it's important to understand that you should **not** do this if you have already pushed your last commit to GitHub as you are effectively rewriting history and all sorts bad things may happen! 

\  

```{r rev4, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert4.png")
```

\  

If you spot a mistake that has happened multiple commits back or you just want to revert to a previous version of a document you have a number of options.   

**Option 1** - (probably the easiest but very unGit - but like, whatever!) is to look in your commit history in RStudio, find the commit that you would like to go back to and click on the 'View file @ ' button to show the file contents.

\  

```{r rev5, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert5.png")
```

\  

You can then copy the contents of the file to the clipboard and paste it into your current file to replace your duff code or text. Alternatively, you can click on the 'Save As' button and save the file with a different file name. Once you have saved your new file you can delete your current unwanted file and then carry on working on your new file. Don't forget to stage and commit this new file.

\  

```{r rev6, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert6.png")
```

\

**Option 2** - (Git like) Go to your Git history, find the commit you would like to roll back to and write down (or copy) its SHA identifier. 

\  

```{r rev7, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert7.png")
```

\  

Now go to the Terminal in RStudio and type `git checkout <SHA> <filename>`. In our case the SHA key is `2b4693d1` and the filename is `first_doc.Rmd` so our command would look like this:

```
git checkout 2b4693d1 first_doc.Rmd
```

The command above will copy the selected file version from the past and place it into the present. RStudio may ask you whether you want to reload the file as it now changed - select yes. You will also need to stage and commit the file as usual.  

If you want to revert all your files to the same state as a previous commit rather than just one file you can use (the single 'dot' `.` is important otherwise your HEAD will detach!):

```
git rm -r .
git checkout 2b4693d1 .

```

Note that this will delete all files that you have created since you made this commit so be careful!

#### Staged, committed and pushed {-}

This is the scenario we warned you about above. Everything in this section happens in the Terminal because the Git pane simply has no equivalent, so if the change of interface feels abrupt that's why. If you have already pushed your commits to GitHub you can use the `git checkout` strategy described above and then commit and push to update GitHub (although this is not really considered 'best' practice). Another approach would be to use `git revert` (Note: as far as we can tell `git revert` is not the same as the 'Revert' option in RStudio). The `revert` command in Git essentially creates a new commit based on a previous commit and therefore preserves all of your commit history. To rollback to a previous state (commit) you first need to identify the SHA for the commit you wish to go back to (as we did above) and then use the `revert` command in the Terminal. Let's say we want to revert back to our 'First commit' which has a SHA identifier `d27e79f1`. 

\  

```{r rev8, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert8.png")
```

\  

We can use the `revert` command as shown below in the Terminal. The `--no-commit` option is used to prevent us from having to deal with each intermediate commit. 

```
git revert --no-commit d27e79f1..HEAD
```

Your `first_doc.Rmd` file will now revert back to the same state as it was when you did your 'First commit'. Notice also that the `first_doc.pdf` file has been deleted as this wasn't present when we made our first commit. You can now stage and commit these files with a new commit message and finally push them to GitHub. Notice that if we look at our commit history all of the commits we have made are still present.

\  

```{r rev9, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert9.png")
```

\  

and our repo on GitHub also reflects these changes

\  

```{r rev10, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/revert10.png")
```

### Collaborate with Git {#collab}

GitHub is a great tool for collaboration, it can seem scary and complicated at first, but it is worth investing some time to learn how it works. What makes GitHub so good for collaboration is that it is a *distributed system*, which means that every collaborator works on their own copy of the project and changes are then merged together in the remote repository. There are two main ways you can set up a collaborative project on GitHub. One is the workflow we went through above, where everybody connects their local repository to the same remote one; this system works well with small projects where different people mainly work on different aspects of the project but can quickly become unwieldy if many people are collaborating and are working on the same files (merge misery!). The second approach consists of every collaborator creating a copy (or **fork**) of the main repository, which becomes their remote repository. Every collaborator then needs to send a request (a **pull request**) to the owner of the main repository to incorporate any changes into the main repository and this includes a review process before the changes are integrated. More detail of these topics can be found in the [Further resources](#resources) section.

### Git tips

Generally speaking you should commit often (including amended commits) but push much less often. This makes collaboration easier and also makes the process of reverting to previous versions of documents much more straight forward. We generally only push changes to GitHub when we're happy for our collaborators (or the rest of the world) to see our work. However, this is entirely up to you and depends on the project (and who you are working with) and what your priorities are when using Git. 

\  

If you don't want to track a file in your repository (maybe they are too large, private or transient) you can get Git to ignore the file by right clicking on the filename in the Git pane and selecting 'Ignore...'

\  

```{r tip1, echo=FALSE, out.width="70%", fig.align="center"}
knitr::include_graphics(path = "images/tip1.png")
```

\  

This will add the filename to the `.gitignore` file. If you want to ignore multiple files or a particular type of file you can also include wildcards in the `.gitignore` file. For example to ignore all `png` files you can include the expression `*.png` in your `.gitignore` file and save.

\  

If it all goes pear shaped and you end up completely trashing your Git repository don't despair (we've all been there!). As long as your GitHub repository is good, all you need to do is delete the offending project directory on your computer, create a new RStudio project and link this with your remote GitHub repository using [Option 2](#opt2). Once you have cloned the remote repository you should be good to go. 

## Further resources {#resources}

There are many good online guides to learn more about git and GitHub and as with any open source software there is a huge community that can be a great resource:

- The British Ecological Society guide to [Reproducible Code][BES_code_guide]

- The [GitHub guides][github_guides]

- The Mozilla Science Lab [GitHub for Collaboration on Open Projects guide][mozilla]

- Jenny Bryan's [Happy Git and GitHub][git_happy]. We borrowed the idea (but with different content) of RStudio first, RStudio second in the 'Setting up a version controlled Project in RStudio' section. 

- Melanie Frazier's [GitHub: A beginner's guide to going back in time (aka fixing mistakes)][revert-git]. We followed this structure (with modifications and different content) in the 'Reverting changes' section.   

- If you have done something terribly wrong and don't know how to fix it try [Oh Shit, Git][Oh_Shit_Git] or if you're easily offended [Dangit, Git][dang_it_git]

These are only a couple of examples, all you need to do is Google "version control with git and GitHub" to see how huge the community around these open source projects is and how many free resources are available for you to become a version control expert.

```{r links, child="links.md"}
```