-
Notifications
You must be signed in to change notification settings - Fork 2
/
github_rstudio.Rmd
166 lines (120 loc) · 7.14 KB
/
github_rstudio.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
```{r, echo=FALSE}
# adjust and load as needed
source(file = "setup.R")
```
# GitHub and RStudio
## Objectives
:::objectives
* Link an RStudio project with GitHub
* Create and edit files in RStudio
* Commit and push changes to GitHub
:::
## Using GitHub from RStudio
Although you can do more or less all the version control aspects via the GitHub website, this is not very convenient when you are working on your R projects. Now you have an idea of how the GitHub workflow works, we can start to integrate these version control concepts with RStudio.
### Linking Git and RStudio
To use Git from within RStudio you need to make sure that Git can be found by RStudio.
If you haven't done so already, make sure to go to: `Tools` > `Global Options` > `Git/SVN` and check that 'Enable version control interface for RStudio projects` is enabled. Also, check that the path to Git is present and correct.
```{r git_options, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_options_rstudio.png")
```
### Starting a new project under Git control
If you want version control of your R project, you need to make sure that the project is under control of Git.
The easiest way to start this is by creating a **new project** that is **linked to an existing GitHub repository**.
We can link a new project to the GitHub repository that we generated previously. To do this, we need to copy the URL for this repository. To do this, you have to go to the repository page and click on the `Clone or download` button. You can then copy the URL as shown below:
```{r git_rstudio_01, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_01.png")
```
Next, we need to create a new project. Go to `File` > `New Project` > `Version Control` > `Git`.
```{r git_rstudio_02, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_02.png")
```
```{r git_rstudio_03, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_03.png")
```
In `Repository URL` paste the link to your GitHub repository.
Give the project a name (avoid spaces and try to use a meaningful name) and tell RStudio where to save it.
```{r git_rstudio_04, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_04.png")
```
:::note
It is useful to tick the `Open in a new session` box, so that your project opens in a new RStudio session. That way RStudio opens a session with a clean environment.
:::
Your project will open and your RStudio session should now have an extra tab in the top right corner (where your Environment is), named `Git`. This is where all the changes will show up as you work on your project.
```{r git_rstudio_05, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_05.png")
```
These options can also be found by using the
```{r git_toolbar_button, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_toolbar_button.png")
```
button in the toolbar. When you have opened a file and look at the options under this button it also enables you to find differences from the last commit (if there are any) or view the commit history of that file.
```{r git_rstudio_06, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_06.png")
```
### Changes and your remote repository
Let's make some changes to our local repository, which is now under Git control. Here we are first creating a folder called `notebooks` and adding an R Markdown file named `01_import_and_clean_data.Rmd`.
Once you have created the file you'll see the folder appearing in the `Git` tab. When you tick the `Staged` box, the `Status` changes to Added. This means that Git is tracking your file and will include it in the next commit.
```{r git_rstudio_untracked, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_untracked_changes.png")
```
```{r git_rstudio_tracked, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_tracked_changes.png")
```
There are a few other icons that can appear in the Git pane, so here is an overview:
*
```{r results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/rstudio_untracked_button.png")
```
, **untracked** file. Git has not seen this before and it needs to be added before changes are tracked.
*
```{r results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/rstudio_added_button.png")
```
, **added** file. The file is now tracked by Git.
*
```{r results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/rstudio_modified_button.png")
```
, **modified** file. The file has been modified since the last commit.
*
```{r results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/rstudio_deleted_button.png")
```
, **deleted** file. The file has been deleted since the last commit.
When we edit the file a bit we can see how it changed by clicking on the `Diff` button in the `Git` toolbar.
```{r git_rstudio_differences, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_diff.png")
```
If we are happy with the changes then we can commit them. You can do this by pressing the `Commit` button in the `Git` tab and adding a commit message. All the files that are staged will be included in that particular commit. If there are files that you do not want to commit yet then you can untick them before pressing the `Commit` button.
```{r git_rstudio_commit, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_commit.png")
```
To ensure that the changes end up on your remote repository you need to **push** the changes. To do this, press the `Push` button in the top right corner. RStudio will give you a message that the changes are pushed:
```{r git_rstudio_push, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/git_rstudio_push.png")
```
## Exercise: Version control in RStudio
::: exercise
To get us going, we need to have a repository to play with. You can either use the repository you've created previously, or create a new one:
1. Create a new repository on GitHub
2. Create a new R Project under version control
3. Link the R Project with the remote repository
:::
## Exercise: Branching and changes
::: exercise
Now we've got a project under version control we can practice what we'll do if we want to create a new feature to our existing repository, but do not want to send that to the `main` branch (yet). To do this, we use the following steps:
1. Create a new branch (e.g. `new_notebook` or anything that describes the feature you're adding) from within RStudio. To do this, use the following button in the `Git` pane:
```{r new_branch_button, results='markup', echo=FALSE, purl=FALSE}
knitr::include_graphics("img/new_branch_button.png")
```
2. Create a `notebooks` folder and save a new R Markdown file in it.
3. Ensure that changes to the new file are tracked.
4. Make some changes to the file and commit them.
5. Push the changes to the remote repository.
:::
## Key points
:::keypoints
* You can link repositories to RStudio by cloning them
* Once cloned and under version control, you can commit and push changes to the remote repository
:::
# References