-
Notifications
You must be signed in to change notification settings - Fork 265
/
Copy pathchapter_3.Rmd
435 lines (374 loc) · 19.2 KB
/
chapter_3.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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
---
title: "Lecture 3: Git & R Studio workflow"
subtitle: "Version Control"
author: "Chuan-Peng"
institute: "NNU"
date: "2024/03/10"
output:
xaringan::moon_reader:
css: [default, css/Font_Style.css]
lib_dir: libs
nature:
highlightStyle: github
highlightLines: true
countIncrementalSlides: false
---
class: center, middle
<span style="font-size: 60px;">第三讲</span> <br>
<span style="font-size: 50px;"> Git & R Studio工作流</span> <br>
<span style="font-size: 30px;">版本控制</span> <br>
<br>
<br>
<span style="font-size: 30px;">胡传鹏</span> <br>
<span style="font-size: 30px;">2024/03/10</span> <br>
<br>
<br>
<br>
<br>
Reference: <br>
Vuorre, M., & Curley, J. P. (2018). Curating research assets: A tutorial on the Git version control system. Advances in Methods and Practices in Psychological Science, 1(2), 219-236.
---
<br>
<br>
<h1 lang="en" style="font-size: 60px;">Contents</h1>
<br>
<br>
<br>
<br>
<span style="font-size: 45px;">Goal of Chp 3</span></center> <br>
<span style="font-size: 45px;">3.1 Files and Folders System</span></center> <br>
<span style="font-size: 45px;">3.2 Git and GitHub</span></center> <br>
<span style="font-size: 45px;">3.3 Local Version Control</span></center> <br>
<span style="font-size: 45px;">3.4 Remote Version Control</span></center> <br>
<br>
---
## <h1 lang="en">Goal of Chp 3</h1>
<br><img src="./picture/chp3/goal.png" width="50%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
---
<br>
<br>
<br>
<br>
<span style="font-size: 60px;">3.1 Files and Folders System</span></center> <br>
<br>
<span style="font-size: 30px;"> - 3.1.1 Why</span> <br>
<span style="font-size: 30px;"> - 3.1.2 How to improve</span> <br>
<span style="font-size: 30px;"> - 3.1.3 Recommended Structure</span> <br>
---
## <h1 lang="en">3.1.1 Why</h1>
<br><img src="./picture/chp3/messy files.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
---
## <h1 lang="en">3.1.2 How to improve</h1>
<img src="./picture/chp3/files contrast.png" width="80%" style="display: block; margin-left: auto; margin-right: auto;">
- 制定一定的命名规则；
- 创建清晰的层级结构，并且使用文件夹分类；
- 定期清理和维护；
- ……
---
## <h1 lang="en">3.1.3 Recommended Structure</h1>
<br>
- 1_Protocol <br>
- 2_Literature_Search <br>
- 3_Article_Screen <br>
- 4_Data_Extraction <br>
- 5_Analysis <br>
- 6_Reports <br>
<br>
- .git <br>
- .gitignore <br>
- README.md(.txt) <br>
<br>
<br>
<br>
<br>
Reference: <br>
[https://psych-transparency-guide.uni-koeln.de/folder-structure.html](https://psych-transparency-guide.uni-koeln.de/folder-structure.html)
---
## <h1 lang="en">Reminder</h1>
<br><img src="./picture/chp3/false clean.png" width="50%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 不要让你的文件夹外部看起来非常整洁 <br>
- 但当打开几个文件夹后，内部文件的存放毫无逻辑 <br>
---
<br>
<br>
<br>
<br>
<span style="font-size: 60px;">3.2 Git and GitHub</span></center> <br>
<br>
<span style="font-size: 30px;">- 3.2.1 Version Control</span> <br>
<span style="font-size: 30px;">- 3.2.2 Git</span> <br>
<span style="font-size: 30px;">- 3.2.3 GitHub</span> <br>
---
## <h1 lang="en">3.2.1 Version Control</h1>
<img src="./picture/chp3/version control.png" width="40%" style="display: block; margin-left: auto; margin-right: auto;">
- 版本控制(Version Control)是一种管理文件修改历史的系统，特别是用于源代码管理。通常可以分为本地版本控制与远程版本控制两大类。 <br>
- 本地版本控制系统主要在用户的个人计算机上运行，管理和跟踪文件或项目的历史版本。它允许用户在自己的设备上回退到旧版本、比较文件改动、恢复丢失的文件等，而不依赖于网络连接。 <br>
- 远程版本控制系统则侧重于团队协作和共享资源，通常依托于服务器或云服务。它允许多个用户或团队成员在共同的项目上工作，管理和合并彼此的贡献，同时保持项目的同步和一致性。 <br>
---
## <h1 lang="en">3.2.2 Git</h1>
<img src="./picture/chp3/git.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- Git是目前最常用的免费开源的版本控制的工具。 <br>
- 首先，我们要下载Git(https://git-scm.com/downloads)。 <br>
---
## <h1 lang="en">3.2.2 Git</h1>
<img src="./picture/chp3/choice.png" width="25%" style="display: block; margin-left: auto; margin-right: auto;">
- Git支持多种运行模式，主要通过两个途径：终端（Terminal）和图形用户界面（GUI Panel）。 <br>
- 终端途径提供了全面的功能访问权限，适用于各种命令行界面，包括Git Bash、CMD、R Terminal等。这种方式允许用户执行复杂的Git命令和操作，适合需要深度控制和定制Git工作流的场景。<br>
- 图形用户界面（GUI Panel）则提供了更为直观的操作方式，用户只需通过点击即可完成操作，但这种方式可能不支持某些高级功能。这类界面包括R Studio中的Git面板和GitHub Desktop等，它们适合那些偏好图形界面或不需要执行复杂Git命令的用户。<br>
---
## <h1 lang="en">3.2.3 GitHub</h1>
<img src="./picture/chp3/github.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
- GitHub是全球最大的开源的在线软件源代码托管服务平台，使用Git作为版本控制软件。 <br>
- 在2018年，GitHub被微软公司收购。潜在的平替平台：Gitee, GitLab, Bitbucket。 <br>
- 注册一个GitHub账号( https://github.com )。<br>
- ~~使用科学上网工具时较为稳定，推荐使用outlook, gmail, icloud, hotmail, yahoo等"你懂的"邮箱~~
---
## <h1 lang="en">3.2.3 GitHub</h1>
<br> <br><img src="./picture/chp3/new repo1.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 以下将简单介绍GitHub的基本操作。<br>
- 使用GitHub创建仓库：在自己的用户界面找到repository，点击new。 <br>
---
## <h1 lang="en">3.2.3 GitHub</h1>
<br><img src="./picture/chp3/new repo2.png" width="50%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 设定一个repository的名字，创建README文件，然后点击create repository。<br>
---
## <h1 lang="en">3.2.3 GitHub</h1>
<img src="./picture/chp3/readme.png" width="80%" style="display: block; margin-left: auto; margin-right: auto;">
- README文件是位于项目根目录中的文本文件（通常为README.md、README.txt等），提供了关于项目的基本信息。 <br>
- 基于Markdown语法，图中为常见的使用情况。 <br>
- 本课的PPT由xaringan包生成，R Markdown，在Markdown的基础上进行扩展。 <br>
---
## <h1 lang="en">3.2.3 GitHub</h1>
<br><img src="./picture/chp3/first commit.png" width="80%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- Commit:向GitHub提交更改。 <br>
---
## <h1 lang="en">3.2.3 GitHub</h1>
<br><img src="./picture/chp3/history.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- History:查看历史版本。 <br>
---
## <h1 lang="en">3.2.3 GitHub</h1>
<br><img src="./picture/chp3/fork.png" width="70%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- Fork:复制一个已存在的代码仓库到自己的账户下,允许在不影响原始仓库的情况下自由地开发和修改代码。<br>
---
## <h1 lang="en">3.2.3 GitHub</h1>
<br>
<br>
<img src="./picture/chp3/pull request1.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- Pull request:通知机制，告诉项目的维护者你已经完成了一段代码的修改并推送到了一个仓库。<br>
---
<br>
<br>
<br>
<br>
<span style="font-size: 60px;">3.3 Local Version Control</span></center> <br>
<br>
<span style="font-size: 30px;">- 3.3.1 Local Version Control</span> <br>
<span style="font-size: 30px;">- 3.3.2 Creating Git repository for project</span> <br>
<span style="font-size: 30px;">- 3.3.3 Adding files to Git</span> <br>
<span style="font-size: 30px;">- 3.3.4 Keeping track of changes with Git</span> <br>
<span style="font-size: 30px;">- 3.3.5 Accessing files’ past versions</span> <br>
<span style="font-size: 30px;">- 3.3.6 Telling Git to ignore files</span> <br>
---
## <h1 lang="en">3.3.1 Local Version Control</h1>
<br><img src="./picture/chp3/local.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
---
## <h1 lang="en">3.3.2 Creating Git repository for project</h1>
<br><img src="./picture/chp3/new project1.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 在R Studio中创建一个本地的新项目，并创建其Git repository。 <br>
---
## <h1 lang="en">3.3.3 Adding files to Git</h1>
<br><img src="./picture/chp3/add files1.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 默认情况下，R Studio中Git位于右上角的子窗口。 <br>
- 点击commit，会跳出Git面板。 <br>
---
## <h1 lang="en">3.3.3 Adding files to Git</h1>
<br><img src="./picture/chp3/add files2.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 勾选更新的文件，向Git repository提交更改。 <br>
---
## <h1 lang="en">3.3.3 Adding files to Git</h1>
<br><img src="./picture/chp3/add files3.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 提交更改时不要忘记填写commit message，否则会报错。 <br>
---
## <h1 lang="en">3.3.3 Adding files to Git</h1>
<br><img src="./picture/chp3/add files4.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 正常提交更改后会弹出如图所示的窗口。 <br>
---
## <h1 lang="en">3.3.3 Adding files to Git</h1>
<img src="./picture/chp3/add files5.png" width="90%" style="display: block; margin-left: auto; margin-right: auto;">
- 在R Studio中创建一个readme.txt文件（File->New File->Text File），重复上述步骤。 <br>
---
## <h1 lang="en">3.3.4 Keeping track of changes with Git</h1>
<br><img src="./picture/chp3/add files6.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 修改readme文件并提交，Git面板中会出现前后内容的比较。 <br>
---
## <h1 lang="en">3.3.5 Accessing files’ past versions</h1>
<img src="./picture/chp3/add files7.png" width="80%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 点击Git面板中的History按钮，会弹出一个列出了所有的提交历史的窗口。 <br>
- 点击任何一个提交，查看该提交的详细信息，包括具体的更改内容。 <br>
---
## <h1 lang="en">3.3.6 Telling Git to ignore files</h1>
<img src="./picture/chp3/gitignore1.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 在R Studio右下角的子窗口Files处点击‘.gitignore’。 <br>
---
## <h1 lang="en">3.3.6 Telling Git to ignore files</h1>
<img src="./picture/chp3/gitignore2.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 修改‘.gitignore’，向Git repository提交修改。 <br>
- 图中的修改分别表示忽略test1整个文件夹、忽略test2文件夹中所有.txt文件、忽略test3文件夹中的secret.txt。<br>
---
## <h1 lang="en">3.3.6 Telling Git to ignore files</h1>
<img src="./picture/chp3/gitignore3.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
- 上面的表格总结了修改.gitignore的常用语法，供参考。 <br>
- 在.gitignore文件中规则按顺序执行，后面的规则可以覆盖前面的规则。<br>
---
## <h1 lang="en">3.3.6 Telling Git to ignore files</h1>
<img src="./picture/chp3/gitignore4.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
- 关闭R Studio，在test文件夹中创建3个子文件夹，test1、test2、test3。 <br>
- 每个子文件夹中都包括‘test.txt’,‘secret.txt’两个文件。<br>
---
## <h1 lang="en">3.3.6 Telling Git to ignore files</h1>
<br><img src="./picture/chp3/gitignore5.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- R Studio右上角的子窗口应该只存在如图所示的更改，其他修改都被Git忽略。 <br>
---
## <h1 lang="en">3.3.6 Telling Git to ignore files</h1>
<br><img src="./picture/chp3/bug.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 但有时候事情并不会那么顺利，如图所示，Git并没有如预期那样忽略指定的文件。 <br>
- 出现了bug。<br>
---
## <h1 lang="en">3.3.6 Telling Git to ignore files</h1>
<img src="./picture/chp3/debug.png" width="80%" style="display: block; margin-left: auto; margin-right: auto;">
- 请保持冷静，跟随以下步骤来进行debug： <br>
- 是不是先添加的文件后修改的gitignore？那么文件可能已被Git跟踪，存在缓存，仅修改gitignore是不够的。可以尝试在左下角子窗口的Terminal下输入git rm --cached -r <目录名>/git rm --cached <文件名>这个命令。<br>
- 不存在缓存问题？请检查一下.gitignore中是否存在语法错误。<br>
- 都不存在？在Terminal输入git check-ignore -v .gitignore检查.gitignore文件是否被Git忽略。如果命令没有任何输出，这意味着 .gitignore 是有效的并被 Git 正确处理。<br>
- ……
---
<br>
<br>
<br>
<br>
<span style="font-size: 60px;">3.4 Remote Version Control</span></center> <br>
<br>
<span style="font-size: 30px;">- 3.4.1 Remote Version Control</span> <br>
<span style="font-size: 30px;">- 3.4.2 linking GitHub repository with a local Git repository</span> <br>
<span style="font-size: 30px;">- 3.4.3 Fork GitHub repository</span> <br>
<span style="font-size: 30px;">- 3.4.4 Push changes to GitHub repository</span> <br>
<span style="font-size: 30px;">- 3.4.5 Pull changes from GitHub repository</span> <br>
<span style="font-size: 30px;">- 3.4.6 Pull request to central GitHub repository</span> <br>
---
## <h1 lang="en">3.4.1 Remote Version Control</h1>
<br><img src="./picture/chp3/remote.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
---
## <h1 lang="en">3.4.2 linking GitHub repository with a local Git repository</h1>
<img src="./picture/chp3/link.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
- 有两种方法，将现有本地Git repository连接到新创建的远程GitHub repository(Method 1);<br>
- 或从远程GitHub repository创建新的本地Git repository(Method 2, clone)。<br>
---
## <h1 lang="en">3.4.2 Method 1</h1>
<img src="./picture/chp3/new repo3.png" width="60%" style="display: block; margin-left: auto; margin-right: auto;">
- 请先在GitHub创建一个新的仓库。 <br>
- 请跳过创建 README、.gitignore 和许可证文件，因为这些文件已在本地Git repository中创建。<br>
---
## <h1 lang="en">3.4.2 Method 1</h1>
<img src="./picture/chp3/new project2.png" width="75%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 目前，RStudio的Git面板 仅允许**在创建新项目时**将本地 Git repository链接到远程存储库，无法将本地现有的 Git repository连接到 GitHub。<br>
- 按图所示创建本地仓库。<br>
---
## <h1 lang="en">3.4.2 Method 1</h1>
<br><img src="./picture/chp3/new repo4.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 在新建的GitHub仓库中获取URL。<br>
---
## <h1 lang="en">3.4.2 Method 1</h1>
<img src="./picture/chp3/new project3.png" width="75%" style="display: block; margin-left: auto; margin-right: auto;">
- 粘贴URL后仓库名字将自动生成，选择本地Git仓库创建的位置。<br>
- 创建后连接成功建立，需要复制旧文件夹的内容并将其粘贴到新的本地仓库中。注意，请先复制.gitignore文件。<br>
---
## <h1 lang="en">3.4.3 Fork GitHub repository</h1>
<br><img src="./picture/chp3/fork.png" width="70%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 合作时推荐大家先将中央仓库fork到自己的仓库,最终通过pull request推送到中央仓库。<br>
---
## <h1 lang="en">3.4.2 Method 2</h1>
<br><img src="./picture/chp3/new repo5.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 从已有的GitHub仓库中获取URL。<br>
---
## <h1 lang="en">3.4.2 Method 2</h1>
<br><img src="./picture/chp3/new project4.png" width="70%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 在R Studio中创建新的版本控制仓库，选择合适的储存路径。<br>
- 创建后连接成功建立，已将已有的仓库克隆到本地。<br>
---
## <h1 lang="en">3.4.4 Push changes to GitHub repository</h1>
<br><img src="./picture/chp3/git push.png" width="70%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 向自己fork的远端GitHub repository推送更新。<br>
- push前不要忘记先commit你的修改！<br>
---
## <h1 lang="en">3.4.4 Push changes to GitHub repository</h1>
<br><img src="./picture/chp3/git push success.png" width="70%" style="display: block; margin-left: auto; margin-right: auto;"> <br>
- 推送成功。<br>
---
## <h1 lang="en">3.4.5 Pull changes from GitHub repository</h1>
<br><img src="./picture/chp3/git pull.png" width="70%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 从远端GitHub repository下拉更新。<br>
- 注意fork的仓库与中央远端GitHub repository保持一致。<br>
---
## <h1 lang="en">3.4.6 Pull request to central GitHub repository</h1>
<br>
<br>
<br>
<img src="./picture/chp3/pull request1.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
---
## <h1 lang="en">3.4.6 Pull request to central GitHub repository</h1>
<br><img src="./picture/chp3/pull request2.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
---
## <h1 lang="en">Advanced</h1>
<br><img src="./picture/chp3/get good.png" width="60%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
- 使用R Studio中的Terminal输入代码也可以实现操作。常用操作代码请搜索git cheatsheet（R Package也有cheatsheet）。<br>
- 可以通过在Terminal输入git clone https://github.com/example/repo.git 将远程仓库克隆到本地。<br>
- 也可以通过在Terminal输入git remote add origin https://github.com/username/reponame.git 与git push -u origin master实现将本地已有的Git repository与远程的GitHub repository建立连接，不需要移动文件位置。<br>
---
<br><img src="./picture/chp3/youTurn.gif" width="35%" style="display: block; margin-left: auto; margin-right: auto;">
<br>
<div style="text-align: center;">
<span style="font-size: 60px;">Now It's Your Turn!</span>
</div>
<br>
---
## Summary
- 项目管理：文件夹管理系统
- Git & Github: 代码管理与版本控制
- 使用R Studio与Git进行本地版本控制
- 使用R Studio, Git与GitHub进行协作版本控制
## Homework
- ddl:下次上课前
<img src="./picture/chp3/homework.png" width="100%" style="display: block; margin-left: auto; margin-right: auto;">