/
git-intro-2018.html
410 lines (267 loc) · 11.7 KB
/
git-intro-2018.html
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
<!DOCTYPE html>
<html>
<head>
<title>Intro to Git</title>
<meta charset="utf-8">
<meta name="author" content="EcoHealth Alliance Data Science Training" />
<meta name="date" content="2018-06-13" />
<link href="libs/remark-css-0.0.1/default.css" rel="stylesheet" />
<link rel="stylesheet" href="eha.css" type="text/css" />
</head>
<body>
<textarea id="source">
class: center, middle, inverse, title-slide
# Intro to Git
### EcoHealth Alliance Data Science Training
### June 13, 2018
---
## Goals of the session
1. Understand why git and Github are used
--
2. Get familiar with the 4-7 git verbs that will make up >95% of your git use, and practice with the command line and the Rstudio git interface.
--
3. Know how to find help - be familiar with this doc as a reference, and be familiar with the terminology so you know what to Google when you get stuck
--
4. Develop generous habits toward your teammates and, more importantly, toward your future self
---
layout: inverse
background-image: url(https://i.imgur.com/GVJ06OK.jpg)
---
layout: false
## Why Use Git?
- For **version control**
- track changes in code
- revert to old versions when you commit a terrible error
--
- To avoid this:
<center>
<img src="figs/filenames.gif", width = 462, height = 372></img>
</center>
---
## Why Use Github?
- To share data and code across teams
- To track and merge changes in code from multiple collaborators on a project
<center>
<img src="figs/gitflow.png", width = 605, height = 370>
</center>
---
## Barriers to entry
--
- You (and your team/supervisor) already have a versioning system already set up.
--
- You typically work on analyses by yourself.
--
- Git co-opts regular words (fork, tree, push, commit) and assigns them *extremely* Git-specific definitions that are tremendously easy to confuse until you get the hang of it.
---
## Getting Started: register on Github.com
- Register for a *public* (free) account
- Send your Github username to Noam [ross@ecohealthalliance.org](ross@ecohealthalliance.org) or Toph [allen@ecohealthalliance.org](allen@ecohealthalliance.org) so they can add you to the EHA organizational Github and give you read access to private repos
- EHA-hosted files can be PRIVATE to the organization. Any data or code that you host on your personal Github will be public.
---
## Git terminology
.pull-left[
- `tree`: a directory or folder of files. trees can have multiple branches.
- `branch`: a version of the tree. You can make a new branch if you want to test out changes in a file, but don’t want to alter the original.
- `master` or `master branch`: the trunk of the tree.
]
.pull-right[
<img src="figs/gittree.png", width = 300, height 390></img>
]
---
## Git terminology
- `repo` or `repository`: a file directory hosted on Github. This should include everything you need for a project - raw data, code/scripts, intermediate files, etc.
- `remote`: an external place that holds your tree. For us, the remote will be a path to a Github repo, e.g. [https://github.com/brooke-watson/intro-to-git](https://github.com/brooke-watson/intro-to-git)
- `origin`: The default name of the remote.
---
## Git verbs
- `git init` initializes a git repo from the command line *inside* a folder.
--
- Alternately, you can initialize a git repo when you start a new project in R Studio.
---
## Git verbs
.pull-left[
### On the way down:
- `fork`: copy someone else's remote to your remote
- **`clone`: copy a remote onto your computer**
- `fetch`: update your clone from a remote that already exists
- **`pull`: fetch updates + check them out into your working directory**
- `merge`: resolve conflicts between the remote and your local repository
]
--
.pull-right[
### On the way up:
- **`add` or `stage`: get your changes ready to be saved**
- **`commit`: save a record to your repository. A commit is basically a super-save.**
- **`push`: copy that record from your repository (your local computer) to your remote (Github)**
]
---
## Git structure
<img src="figs/diagram.svg", width = 700, height = 200></img>
- Remote = Github
- Repository = Git = your local record of `commit`ted saves
- Workspace = The regular-degular-schmegular files you work on.
- Index = Staging area where you can look at the changes you've made before you commit them. (R Studio has a nice GUI for looking at `git diff`s).
---
# Practice!
---
## First things first: find the command line
.pull-left[
- In Mac: `cmnd` + `space`, type "terminal", hit Enter
<img src="figs/terminal1.png", width = 373, height = 172, border = 1></img>
]
.pull-right[
- In Windows: open the start menu and find "git bash."
]
---
## Navigate the command line to where you want it
- In terminal, your prompt will be something like `Brookes-MacBook-Air:Dropbox (EHA) Watson$`
- typing `pwd` at the command line `p`rints your `w`orking `d`irectory
- `cd <path>` `c`hanges your working `d`irectory to `<path>`
- When you `clone` the git repository, git will download all the files in that repo into your current working directory - basically copying that folder into your home computer
---
## Fork someone else's repo
- This makes a local copy of someone else's project so you can make changes without altering their original.
- You may not do this often. For example, if you're working by yourself, or if you have contributor privileges to a project, you'll go straight to `cloning`.
- Forks of private repos *stay private.*
- Fork [https://github.com/brooke-watson/intro-to-git.](https://github.com/brooke-watson/intro-to-git) now.
---
## Clone a repo
- Go to YOUR copy of the repo: [https://github.com/YOUR-USERNAME/intro-to-git](https://github.com/YOUR-USERNAME/intro-to-git).
- Click the "Clone or Download" button and copy the link.
- Go back to your command line, and `cd` into the directory where you want this to live.
- `git clone <paste your link here>`.
- Your files are there!
- `cd intro-to-git` to get inside the folder
---
## Check status and create a branch
- Check your status with `git status`
- Should see `"On Branch Master" "Your branch is up-to-date with 'origin/master’"`
- Create and checkout a branch to work from:
- `git checkout -b <branch_name>`
- EX: `git checkout -b myname-branch`
- `git status`
---
## Make a change and check your status
- Change anything you want about the directory:
- Using the command line
- e.g. `mkdir oh-boy-a-new-folder`
- e.g. `touch wow-what-a-new-text-file.txt`
- Or, add/edit the folder interactively, the way you normally would.
- e.g.: Download your favorite .gif or picture, and move it to `intro-to-git/figs`.
- `git status` again to see your changes.
---
## Make a change and check your status
You should see something like this:
<br>
---
## Pause because really: what a good wholesome gif.
---
## Add (stage) changes and look at the differences
- Add file to changes that you want to “stage”: `git add <filename>`
- e.g. (`git add 'figs/dwight-howard-cookie-challenge.gif'`)
- Sometimes you might use `git add . ` to add ALL untracked files - use with caution!!
- can also use `git add *.Rmd` to add all the .Rmd files, for example
---
## Git diff
- `git diff —-cached` to see your changes
- It's easier to use a GUI to do this
- RStudio has a great one
- [happygitwithr.com/](happygitwithr.com) is very helpful if/when you want to use Git/Github from within RSTudio
- Highly recommend if you are using R!!
---
## Rstudio git diff GUI
<img src="figs/gitdiff.png", width = 700, height = 521></img>
---
## Commit your changes:
- type `git commit -m "Wow, we did it, what a commit”`
- don’t leave out the `-m`: just doing `git commit` will open a dreadful text editor that you’ll never escape.
- Try to write a **useful** message that your collaborators (and/or Future You) might be able to understand
<br>
---
## Push changes to Github
- Check your remote: `git remote -v` (if you started by cloning a repo from GitHub, your origin should already be set)
- Push your changes to the remote server: `git push <remote-name> <your-branch>`
- e.g. `git push origin myname-branch`
- Check [github.com/YOUR-USERNAME/intro-to-git](github.com/YOUR-USERNAME/intro-to-git) to check that your changes are there
- You did it!
---
## Submit a pull request (PR)
- Open the repo in GitHub and select your branch
- You should see *"compare and pull request"*. This will bring up a summary of your changes and show you what branch you are merging.
- Edit your message and click submit. Now you should see your pull request show up in the pull requests tab!
- In a real project your PR may be discussed and reviewed. Stakeholders may suggest changes or updates and (hopefully) eventually your code will be merged!
---
# Tips
---
## Don't accidentally make (y)our private research data public!
.pull-left[
### Start Here
<img src="figs/new-github.png", width = 375, height = 250, border = 1></img>
]
.pull-right[
### Not here
<img src="figs/no-github.png", width = 375, height = 250></img>
... when creating a new repository.
]
---
## Tips
- When you get stuck, do your Googles.
- If you do things in the right order, most of what you want to accomplish can be done with about 7 commands (`clone, pull, checkout, status, add, commit, push`).
- Always `git pull` before committing and pushing.
- If you get really stuck, save your folder in a new location, delete the whole thing, and re-clone from Github.
- This is the Github equivalent of "turning it off and turning it back on."
---
## If you get confused, you're not alone
<center>
---
## Resources
- Command line cheat sheet:
- [https://www.git-tower.com/blog/command-line-cheat-sheet/](https://www.git-tower.com/blog/command-line-cheat-sheet/)is
- Git Cheat sheet:
- [https://www.git-tower.com/blog/git-cheat-sheet](https://www.git-tower.com/blog/git-cheat-sheet)
- Happy Git with R: makes things very easy if using from RStudio:
- [http://happygitwithr.com/](http://happygitwithr.com/)
- Noam's reproducibility document:
- [https://github.com/ecohealthalliance/eha-reproducibility](https://github.com/ecohealthalliance/eha-reproducibility)
---
# Questions?
</textarea>
<script src="https://remarkjs.com/downloads/remark-latest.min.js"></script>
<script>var slideshow = remark.create({
"highlight": "tango",
"countIncrementalSlides": false
});
if (window.HTMLWidgets) slideshow.on('afterShowSlide', function (slide) {
window.dispatchEvent(new Event('resize'));
});
(function() {
var d = document, s = d.createElement("style"), r = d.querySelector(".remark-slide-scaler");
if (!r) return;
s.type = "text/css"; s.innerHTML = "@page {size: " + r.style.width + " " + r.style.height +"; }";
d.head.appendChild(s);
})();</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre']
}
});
</script>
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement('script');
script.type = 'text/javascript';
script.src = 'https://cdn.bootcss.com/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML';
if (location.protocol !== 'file:' && /^https?:/.test(script.src))
script.src = script.src.replace(/^https?:/, '');
document.getElementsByTagName('head')[0].appendChild(script);
})();
</script>
</body>
</html>