-
Notifications
You must be signed in to change notification settings - Fork 0
/
GitHubPresentation.Rmd
255 lines (183 loc) · 11 KB
/
GitHubPresentation.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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
---
layout: page
title: Version Control with Git
description: notes, links, example code and exercises
---
[next](notes0906-bestpractices.html)
```{r setup, include=FALSE}
---
output:
html_document:
highlight: pygments
pdf_document: default
---
# Berry Consultants Stats Call
# May 28th 2021
# Cora Allen-Savietta, Ph.D.
knitr::opts_chunk$set(echo = FALSE)
```
\bigskip
## Getting Started with GitHub
::: columns
:::: column
- Version Control
- define a clear history by taking "snapshots" as you work
- track only certain files with .gitignore files
- GitHub
- share code with collaborators
- resolve conflicts
- review code with pull requests
- Activity: Clone a repo and make a commit
- Useful Links
::::
:::: column
::::
:::
## Version Control with Git
- Git tracks your changes, allowing you to define a clear history
- Whenever you'd like to add to your history, take a snapshot, called a "commit", and add a message.
- To look at a previous version of a project and its commit message, check out the previous commit, then come back to the newest version.
- Git helps you take care of your future self: *you'll know exactly which version of your code created that design report!*
Let's create a new project directory and see how git can help us track our changes.
```{bash, echo = TRUE, eval=FALSE}
mkdir example-repo # create a new folder
cd example-repo
git init # create a git repository
git status
code readme.md # then make changes to the readme in VSCode
git add readme.md # stages file
git commit -m"starting a readme for docs" # create a new commit with a log message
git log # to see our repos commit history. each commit has a unique ID, called a SHA
git show SHA # use SHA to see only its changes
code readme.md # make new changes to the readme
git diff # see only new differences
git add readme.md # add these changes
git reset # oops! didn't mean to add those
```
Now, you have a git repo!
**What if we have want to add files to this directory, but don't want to track them?**
We *want* to track:
- scripts: any kind of code in R, Rmd, Python, Julia, Fortran...
- text documentation:
- readme files
- data dictionaries
- data analysis pipelines (instructions for reproducing results)
We do *not* want to track:
- large or sensitive data files. (Unauthorized users cannot access private repos, but its still not best practice to track data files.)
- pdfs, images, figures: instead, document how they can be reproduced
- MS Word/Powerpoint documents
To avoid accidentally adding these files, we can use a gitignore file.
```{bash, echo = TRUE, eval=FALSE}
code data.csv # add a data file to the repository. We dont want to track this!
code words.docx # create a word document. We dont want to track this either
git status
code . # VSCode bolds all file names
code .gitignore # create a .gitignore file, add *.csv, *.docx, any other file extensions you dont want to track
git status
git add .gitignore
git commit -m"adding a gitignore file to ignore csv and docx files"
code words2.docx # create another word file
git status # git automatically ignores this new docx file
code . # ignored files are now lighter in VSCode
```
#### Version Control with Git: Summary
- tracks your changes as you work, allowing you to **define a clear history**
- **.gitignore** files help us control what is tracked
- useful commands
**git status**: summarizes changes that are staged/not staged for next commit
**git add**: stages changes
**git reset**: unstages changes
**git diff**: shows differences in files since last commit
**git commit -m"commit message"**: commits stages changes with a message
**git log**: shows git history, with each commit's SHA (id)
**git show SHA**: shows commit's changes and log message
### GitHub: Collaborate and Resolve Conflicts Seamlessly!
One of Git's best features is its ability to create text files that compare two versions of a file. These are called **diffs**. Git creates a **diff** when we compare a current version to one from six months ago. It also create a diff when we compare a version of my current code with Lindsay's code.
GitHub stores a **remote** copy of each repository so that we can create diffs with other people!
#### Sharing our new repository with a collaborator
First, we'll go to GitHub.com, create a new repository, and add our collaborator as a contributor. Then, we'll connect this remote GitHub repo to our local repository by following GitHub's instructions.
```{bash, echo = TRUE, eval=FALSE}
git remote add origin https://github.com/coraallensavietta/example-repo.git
git branch -M main # rename main branch
git push -u origin main # push all of my commits to remote
```
Now, Lindsay and I can collaborate and compare our work using git diffs!
#### Resolving Conflicts during Collaboration
First, let's say Lindsay goes in and makes changes to our readme.md file.
In the meantime, I've also made changes to the readme.md file on my local computer.
```{bash, echo = TRUE, eval=FALSE}
code readme.md # I make changes locally
git add
git commit -m"added info about location of the data dictionary"
git push
```
*CONFLICT!*
Don't worry! This looks scary, but GitHub is great at handling conflicts. That's why we love it!
GitHub will walk us through resolving this conflict.
```{bash, echo = TRUE, eval=FALSE}
git pull # pull Lindsay's changes from the remote
git status
code readme.md # open the file with conflicts and resolve the conflict
git add readme.md # add the resolved version of the files
git commit # commit this newly resolved file
git push # push the resolved version to remote
```
Now, the my local repo and the remote repo on GitHub both have the resolved version of readme.md, which includes both my changes and Lindsay's changes. Lindsay can *pull* it to her local machine and she will have it too!
#### Branches and Code Review
Often we want to test out a new feature before we add it to the main code base. To do this, we create a copy of the main repository, a **branch**, where we can play around with this new code.
```{bash, echo = TRUE, eval=FALSE}
git branch multivar-model # create a new branch to try a multivariate version of the model
git checkout multivar-model # move to this branch
code readme.md # try out this new model!
git add readme.md
git commit -m"trying a multivariate version of the model"
git diff main # compare this branch to the main branch
git push # on no! need to set the remote, just as we did for the main branch
git push --set-upstream origin multivar-model # push changes to the remote repository
```
On the multivar-model branch, I just added a new version of the data analysis model to our repo. Before it's integrated into our main branch, I'd like Lindsay to look it over.
To do this, I'll use [GitHub's pull request process](https://github.com/coraallensavietta/example-repo/pulls) and ask Lindsay to review the code.
#### GitHub: Summary
- Each collaborator has a **local** version git repo on their machine. GitHub stores the **remote** version of each repo. This lets us compare our local files with those stored on GitHub.
- To get your changes, collaborators will **pull** your changes from the remote GitHub repo
- To add their changes, they will **push** to the remote.
- **conflict resolution**: If you've made changes to the same code, you can smoothly handle them with a **merge**, so that you can write code together without overwriting each others work or missing changes.
- GitHub's **branching** and **code review** makes code review quick and easy for better, less buggy code!
### Activity: Clone a GitHub Repo and Make a Commit
Today we will clone the Berry Consultants [Shared Simulation Code Library](https://github.com/BerryConsultants/Shared-Trial-Simulation-Library), so that we can start contributing to it!
**Step 1**: If you don't already have one, [create a GitHub account](https://docs.github.com/en/github/getting-started-with-github/signing-up-for-github/signing-up-for-a-new-github-account) and verify your email address.
**Step 2**: If you haven't done so, email or Slack your user ID to Henrik, Kert, or Pravin so they can add you to the Berry GitHub team.
**Step 3**: Step up Git, following [these instructions](https://docs.github.com/en/github/getting-started-with-github/quickstart/set-up-git#setting-up-git).
If you're on a Mac, you may not need to download Git.
**Step 4**: Cache your GitHub credentials in Git following [these instructions](https://docs.github.com/en/github/getting-started-with-github/getting-started-with-git/caching-your-github-credentials-in-git).
We'll be cloning repositories using HTTPS, so we can use a credential helper so that Git remembers your username and password. At the end, you'll need to create a personal access token, following [these instructions](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token).
**Now you're ready to clone your first repo!**
**Step 5**: Navigate to the folder where you'd like to keep this repo and make sure it's not already a git repository.
```{bash, echo = TRUE, eval=FALSE}
git status # should tell you are not in a git repo
```
**Step 6**: Go to GitHub page and copy the Berry Sim Library's HTTPS URL. Then, go the folder you checked in step one and type in to your terminal:
```{bash, echo = TRUE, eval=FALSE}
git clone https://github.com/BerryConsultants/Shared-Trial-Simulation-Library.git
```
Now, you can explore the repository on your local machine!
**Step 7**: Push your first commit!
Add a new file to the repository, named with your initials: e.g. yourinitials.txt.
```{bash, echo = TRUE, eval=FALSE}
cd testcommits # go into the testcommmits directory
touch your-file-name # create a new file named yourinitials.txt
git add your-file-name # stage your new file using its file name (yourinitials.txt)
git status
git commit -m"pushing my first commit to the Berry Code Library!" # commit with message
git push # push your additions to the remote repository
```
### Useful Links
- Set up VSCode as your default Git editor [here](https://stackoverflow.com/questions/30024353/how-to-use-visual-studio-code-as-default-editor-for-git)
- [Git docs](https://git-scm.com/doc)
- [Collaborate with Pull Requests on GitHub](https://docs.github.com/en/github/getting-started-with-github/quickstart/github-flow)
- [Communicate about projects with Issues, PRs, and team discussions](https://docs.github.com/en/github/getting-started-with-github/quickstart/communicating-on-github)
- [More tips for getting started on GitHub](https://docs.github.com/en/github/getting-started-with-github/quickstart)
- Today I've shown you how to use GitHub in the terminal, but you can also use [RStudio](https://happygitwithr.com/rstudio-git-github.html) or [GitHub's desktop app](https://desktop.github.com/).
- And now that you've caught the GitHub bug, [make your own octocat](https://myoctocat.com/)!
{ width=30% }