Skip to content

Commit 413c28d

Browse files
sstevens2sstevens2
authored
Merge pull request #3 from UW-Madison-DataScience/sstevens-draft-ep2
Starting draft for git episode
2 parents 3a3a8dc + 52e50f4 commit 413c28d

File tree

2 files changed

+194
-71
lines changed

2 files changed

+194
-71
lines changed

‎episodes/git.Rmd

Lines changed: 193 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,248 @@
11
---
2-
title: "Using RMarkdown"
2+
title: "Using git in RStudio"
33
teaching: 10
44
exercises: 2
55
---
66

77
:::::::::::::::::::::::::::::::::::::: questions
88

9-
- How do you write a lesson using R Markdown and `{sandpaper}`?
9+
- How do I setup a repository in GitLab?
10+
- How do I use git to record the history of my code in Rstudio?
1011

1112
::::::::::::::::::::::::::::::::::::::::::::::::
1213

1314
::::::::::::::::::::::::::::::::::::: objectives
1415

15-
- Explain how to use markdown with the new lesson template
16-
- Demonstrate how to include pieces of code, figures, and nested challenge blocks
16+
- Identify the location and functionality of Git integration within RStudio
17+
- Create a repository in GitLab for version control
18+
- Clone a GitLab repository as a project in RStudio
19+
- Make changes to the project, add, and commit them using git
1720

1821
::::::::::::::::::::::::::::::::::::::::::::::::
1922

2023
## Introduction
2124

22-
This is a lesson created via The Carpentries Workbench. It is written in
23-
[Pandoc-flavored Markdown](https://pandoc.org/MANUAL.txt) for static files and
24-
[R Markdown][r-markdown] for dynamic files that can render code into output.
25-
Please refer to the [Introduction to The Carpentries
26-
Workbench](https://carpentries.github.io/sandpaper-docs/) for full documentation.
25+
This lesson will pick up using the ratdat / portal dataset we used in the previous sessions.
2726

28-
What you need to know is that there are three sections required for a valid
29-
Carpentries lesson template:
27+
To get started we need to setup the project we are going to be working with (both in R/RStudio and in GitLab).
28+
You can setup the project first in either place but for this example we will start by creating the repository in GitLab.
3029

31-
1. `questions` are displayed at the beginning of the episode to prime the
32-
learner for the content.
33-
2. `objectives` are the learning objectives for an episode displayed with
34-
the questions.
35-
3. `keypoints` are displayed at the end of the episode to reinforce the
36-
objectives.
30+
## Configuring Git on You computer
3731

38-
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: instructor
32+
Each time we save something into our git history, it associates an email address and a name with it.
33+
Before we get started we will need to configure those using a package called `usethis`.
3934

40-
Inline instructor notes can help inform instructors of timing challenges
41-
associated with the lessons. They appear in the "Instructor View"
35+
First we will install `usethis` in the console by typing:
4236

43-
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
44-
45-
::::::::::::::::::::::::::::::::::::: challenge
37+
```r
38+
install.packages("usethis")
39+
```
4640

47-
## Challenge 1: Can you do it?
41+
Once it finishes we will configure the `user.name` and `user.email` variables to use.
4842

49-
What is the output of this command?
43+
```r
44+
usethis::use_git_config(user.name="Your Name", user.email="[email protected]")
45+
```
5046

47+
Finally, you can check your configuration
5148
```r
52-
paste("This", "new", "lesson", "looks", "good")
49+
usethis::git_sitrep()
5350
```
5451

55-
:::::::::::::::::::::::: solution
52+
## Setting up the GitLab Project
5653

57-
## Output
58-
59-
```output
60-
[1] "This new lesson looks good"
61-
```
54+
First you need to navigate to the [UW-Madison GitLab instance][uw-gitlab] and select the UW-Madison NetID login option.
6255

63-
:::::::::::::::::::::::::::::::::
56+
Next we will create a new project. You can do so by clicking the "+" button then "New project/repository" option in the upper-left hand of the screen OR you can click the blue "New Project" button on the right hand side of the screen. If you do not see the "+" button, it might mean that your sidebar is hidden. To see the sidebar, click the sidebar icon at the top left of your screen.
6457

58+
<!--- screenshot needed: gitlab interface highlighting the + button and new project/repo and new project button -->
6559

66-
## Challenge 2: how do you nest solutions within challenge blocks?
60+
On the "Create new project" page, choose "Create blank project".
6761

68-
:::::::::::::::::::::::: solution
62+
<!--- screenshot needed: Create new project page -->
6963

70-
You can add a line with at least three colons and a `solution` tag.
64+
We will call our project, `ratdat_lib_wksp`.
65+
Note, if you belong to any organizations (like from your dept or lab), you may need to change the project URL to your user instead of the organization.
66+
It will automatically assign the "Project slug" (aka the end of the url for that project) to be the same as the project name.
67+
If you use spaces in your project name, it will replace them with `-` in your project slug.
68+
You also need to choose the visiability level. You can decide what level of visibility you would like your project to have.
69+
I'll make mine public so I can share it with you direclty if you are interested.
70+
You can also decide if you would like it to create a README for your project. Best practice is to have a README for any project so we will keep it checked.
71+
We will skip the option for security testing but this could be an option you want to enable for your code projects.
72+
Then click the "Create project" button.
7173

72-
:::::::::::::::::::::::::::::::::
73-
::::::::::::::::::::::::::::::::::::::::::::::::
74+
<!--- screenshots needed: the create new project page with the options given in the paragraph above highlighted-->
75+
76+
Now that we have created the project we can see the repository. It created a nice README template at the bottom.
77+
78+
<!--- screenshot needed: view of the project repo after creation -->
79+
80+
::::::::: instructor
81+
82+
You may want to give a short orentation to the different parts of the GitLab project webpage that seem relevant here:
83+
For example:
84+
- the file list
85+
- issues/merge requests on the left pane
86+
- project info on the right side (license, changelog etc)
87+
88+
::::::::::::::::::::
89+
90+
## Setting up the Project in RStudio
91+
92+
Next we will `clone` (copy) this project to our computer and make it a project in RStudio.
93+
Before we can do so we need to set up verifying our identity with GitLab.
94+
95+
### GitLab Authentication
96+
97+
We need to set up a special passkey called a Peronal Authenticalion Token (PAT) on GitLab and then we will enter it in RStudio when we need to connect to GitLab.
98+
99+
We need to note both our GitLab username and your PAT so we can use them when we set up the Project on our computer.
100+
In GitLab you can check your username by clicking on your profile icon in the upper left panel. It will say `@FIRSTNAME.LASTNAME` or your `@NetID`, or something to that effect.
101+
Note down your username in a text file so you have it available when you need it later.
102+
103+
To setup the PAT, click the "Settings" option on the left hand side (bottom of the left pane), then choose "Access Tokens".
104+
105+
On the "Project access tokens" page, click the "Add new token" button. Give the token a name specific to the computer you are working from. You can leave the Token description blank.
106+
By default, it will expire in a month. We will leave that setting for now and if you use GitLab after a month, you should go back and give it further permissions or create a new token.
107+
Select "Owner" as the role.
108+
You can leave all the options under "Select Scopes" unchecked, these would be needed if you were setting fine-grained permissions for your token.
109+
Then click "Create project access token".
110+
111+
It will then show the project token in a green box on the screen but we won't be able to access it again so we need to copy it now (we can always setup others if needed later).
112+
Click the copy button to copy the token. Copy this into a text file.
113+
114+
115+
Now that we have set up the authentication, we can create the Project on our computer and setup the connection to GitLab, at the same time.
116+
In GitLab, return to your new project directory `ratdat_lib_wksp` by clicking the link at the top of the page. Then click the blue "Code" button at the top of the directory information.
117+
Then click the copy button to the right of the "Clone with HTTPS" option.
118+
119+
<!--- screenshot needed: the code menu and the copy button from the clone with HTTPS option highlighted"
74120
75-
## Figures
121+
Open RStudio and create a new project with the +shield icon or `File` > `New Project`.
76122
77-
You can also include figures generated from R Markdown:
123+
<!--- screenshot needed: highligting the new project button -->
124+
125+
In the new project wizard, click the "Version Control" option.
126+
On the next page, click the "Git" option.
127+
Paste the HTTPS address you copied in the "Repository URL" option.
128+
It will autofill in the "Project directory name" box with the slug from the URL when you click away from that box, but you can change it if you ever need to (which you will later).
129+
You may want to change where the project is created in your file system, by default it will likely save it in your home folder/`~`.
130+
We will change ours to Desktop so we can find it more easily by clicking the "Browse" button, and then choseing our `Desktop` folder and clicking "Open".
131+
We can then click the "Create project" button.
132+
133+
<!--- screenshots needed of all the project wizard pages with the inputs described above -->
134+
135+
Since we've never authenticated with GitLab before it will ask us for our username.
136+
Type or paste your username and token from the text file into the the username and password boxes respectively.
137+
138+
Now you are in the project for the GitLab Project you set up. You will see the project name in the upper right-hand side of the page.
139+
The file pane in the lower right quadrant of RStudio will also show the...
140+
- `.gitignore` - a file that allows you to have untracked files in the folder on you computer that in the project folder - this was created when we setup the Rproject so git doesn't try to tack some R files that commonly are not tracked with git
141+
- `ratdat_lib_wksp.Rproj` - the Rproject folder (this is nice for reopening your project from the file folder) - this was created when we set up the Rproject since it didn't already exist
142+
- `README.md` - The documentation file that GitLab created for us when we set up the project
143+
144+
145+
## Tracking files with git and RStudio
146+
147+
Let's go check out the "Git" file pane in the upper right quadrant! It wasn't there until we cloned this git repository/project.
148+
It currently lists the two files that were created when we set up the project, `ratdat_lib_wksp.Rproj` and `.gitignore`.
149+
This is because these are new files that have not been tracked with git before.
150+
151+
To track these files in our repository we have to do two steps, first we stage the files and then we commit them to the history of the project/repo.
152+
To stage the files in Rstudio, we can click the checkboxes in the "Staged" column of the Git pane.
153+
When we do this, the status of each file changes from "? ?" to "A" for "Added to the stage".
154+
Then to commit them, we can click the "Commit pending changes" icon in the Git pane.
155+
156+
This pops up a window to "Review Changes" where we can click through the files and see what has changed.
157+
Since both these files are new, they show a big green section of lines in the files. This is called the "diff" it shows the difference before and after the commit. In this case, all new lines were added and are in green.
158+
We could also unstage/reset the files if we decide we don't want to commit them both at the same time (typically you will commit linked changes together but can commit unlinked changes separately).
159+
160+
To commit these changes we also have to write a message about what has changed in this commit in the "Commit message" box.
161+
We will type, "Adding Rproj and gitignore files" and then we can click "Commit"
162+
163+
A git commit window will pop up and have a message that includes a unique identifier code for the commit (called a hash), our commit message, and a summary of what changed in that commit.
164+
We can then click "close" on the window. We can also close the "Review Changes" window.
165+
Now all the files in our project have been tracked with git. We can tell by looking at the "Git pane" because there are not files listed.
166+
This means there are no new files and no new changes to existing files in our project since we last committed it.
167+
168+
169+
::::::: challenge
170+
171+
### Create an R script
172+
173+
Let's practice adding new files and tracking them with git.
174+
175+
Create and Rscript with the following code and then track it with git using the steps we learned.
78176

79-
```{r pyramid, fig.alt = "pie chart illusion of a pyramid", fig.cap = "Sun arise each and every morning"}
80-
pie(
81-
c(Sky = 78, "Sunny side of pyramid" = 17, "Shady side of pyramid" = 5),
82-
init.angle = 315,
83-
col = c("deepskyblue", "yellow", "yellow3"),
84-
border = FALSE
85-
)
86177
```
178+
library(ratdat)
179+
library(tidyverse)
87180
88-
Or you can use standard markdown for static figures with the following syntax:
181+
yearly_counts <- complete_old %>%
182+
  count(year, species_id)
89183
90-
`![optional caption that appears below the figure](figure url){alt='alt text for
91-
accessibility purposes'}`
184+
ggplot(yearly_counts,
185+
       aes(x = year, y = n)) +
186+
       geom_line()
187+
```
92188

93-
![You belong in The Carpentries!](https://raw.githubusercontent.com/carpentries/logo/master/Badge_Carpentries.svg){alt='Blue Carpentries hex person logo with no text.'}
94189

95-
::::::::::::::::::::::::::::::::::::: callout
190+
::: solution
96191

97-
Callout sections can highlight information.
192+
1. Copy the code above
193+
2. Create a new Rscript file
194+
3. Paste the code into the Rscript
195+
5. Run your R code. Make sure it works before we commit it.
196+
4. Add the file by clicking the staged checkbox in the Git pane
197+
5. Click the commit button in the Git pane
198+
6. Add a commit message and click "Commit"
98199

99-
They are sometimes used to emphasise particularly important points
100-
but are also used in some lessons to present "asides":
101-
content that is not central to the narrative of the lesson,
102-
e.g. by providing the answer to a commonly-asked question.
200+
:::::::::::::
103201

104-
::::::::::::::::::::::::::::::::::::::::::::::::
202+
:::::::::::::::::
105203

204+
Now that we have created the file, we notice that our plot looks a bit odd, we need to tell it the groups are the species id's and should be separate lines.
205+
We can color the lines differently at the same time by adding `color = species_id` to our `aes()` function
206+
Let's do so and then save that new version of the file to git.
106207

107-
## Math
208+
The code should now be
209+
```
210+
library(ratdat)
211+
library(tidyverse)
108212
109-
One of our episodes contains $\LaTeX$ equations when describing how to create
110-
dynamic reports with {knitr}, so we now use mathjax to describe this:
213+
yearly_counts <- complete_old %>%
214+
  count(year, species_id)
111215
112-
`$\alpha = \dfrac{1}{(1 - \beta)^2}$` becomes: $\alpha = \dfrac{1}{(1 - \beta)^2}$
216+
ggplot(yearly_counts,
217+
       aes(x = year, y = n,
218+
           color = species_id)) +
219+
       geom_line()
220+
```
113221

114-
Cool, right?
222+
Now that we've made this change, we can commit this new version. Like new files, modified files show up in the Git pane.
223+
Notice this time the status is "M" for modified instead of "? ?" like it was for a new file.
224+
We can still stage it and commit it just as we did with the new file by clicking the checkbox to stage it, clicking commit, then adding a commit message.
225+
Note, before you commit that the Review Changes window how shows red for the previous lines in our code and green for the new lines in our code.
226+
Also the number lines for the removed lines are in the first column and the numbers for the new lines are in the second column.
115227

116-
::::::::::::::::::::::::::::::::::::: keypoints
228+
## Exploring the history of our file changes
117229

118-
- Use `.md` files for episodes when you want static content
119-
- Use `.Rmd` files for episodes when you need to generate output
120-
- Run `sandpaper::check_lesson()` to identify any issues with your lesson
121-
- Run `sandpaper::build_lesson()` to preview your lesson locally
230+
The Git pane has several other features for working with git in RStudio, the other one we will point out is the history part of the "Review Changes" window.
231+
To open it directly you can click the click icon on the Git pane menu.
232+
You can access it by clicking the "History" toggle in the Review Changes window, when it is already open.
233+
The history pane now shows the "timeline" of commits we've added so far, authorship info, and we can click through them to see the diffs for each one.
122234

123-
::::::::::::::::::::::::::::::::::::::::::::::::
235+
## Time to push it!
236+
237+
Finally we can sync these changes with GitLab. Everything, besides the original setup, we have done so far has been on our local computer.
238+
If we reload the GitLab project, nothing has changed. The commits we made aren't there, nor is the script we created.
239+
To get our changes to GitLab we have to "push" them.
240+
In the git pane, we can click the green up arrow. This will then pop up a status as it transfers the changes.
241+
242+
Now in GitLab we can reload the page and we can see the script and our most recent changes.
243+
In GitLab, try exploring the files by clicking on them. You can also see the commits and their diffs by clicking on the "X commits" (where X is the number of commits you've made) link
244+
in the right hand "Project Information" menu or by clicking "Code" and "Commits" buttons on the left hand GitLab menu.
124245

125-
[r-markdown]: https://rmarkdown.rstudio.com/
246+
We've now learned the basis of working with git and GitLab in Rstudio. The setup steps will only need be done once per repository or computer.
247+
The snapshot steps of checking the box (adding a file to stage) and commiting will be done each time you create or modify a file (script).
248+
The syncying step(s) of pushing (and pulling which we will see in the next section) will be done at least when you come to a stopping point (or starting point for pushing).

‎links.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ any links that you are not going to use.
77
[r-markdown]: https://rmarkdown.rstudio.com/
88
[rstudio]: https://www.rstudio.com/
99
[carpentries-workbench]: https://carpentries.github.io/sandpaper-docs/
10-
10+
[uw-gitlab]: https://git.doit.wisc.edu/

0 commit comments

Comments
 (0)