/
github-version-control.html
507 lines (468 loc) · 64.1 KB
/
github-version-control.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
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
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>The Open Digital Archaeology Textbook</title>
<meta name="description" content="The Open Digital Archaeology Textbook combines instructive text with a computational DA laboratory">
<meta name="generator" content="bookdown 0.7 and GitBook 2.6.7">
<meta property="og:title" content="The Open Digital Archaeology Textbook" />
<meta property="og:type" content="book" />
<meta property="og:image" content="images/brandon-green-321795-unsplash.jpg" />
<meta property="og:description" content="The Open Digital Archaeology Textbook combines instructive text with a computational DA laboratory" />
<meta name="github-repo" content="o-date/draft" />
<meta name="twitter:card" content="summary" />
<meta name="twitter:title" content="The Open Digital Archaeology Textbook" />
<meta name="twitter:description" content="The Open Digital Archaeology Textbook combines instructive text with a computational DA laboratory" />
<meta name="twitter:image" content="images/brandon-green-321795-unsplash.jpg" />
<meta name="author" content="Shawn Graham, Neha Gupta, Jolene Smith, Andreas Angourakis, Andrew Reinhard, Kate Ellenberger, Zack Batist, Joel Rivard, Ben Marwick, Michael Carter, Beth Compton, Rob Blades, & Cristina Wood">
<meta name="date" content="2018-12-14">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="prev" href="project-management-basics.html">
<link rel="next" href="open-notebook-research-scholarly-communication.html">
<script src="libs/jquery-2.2.3/jquery.min.js"></script>
<link href="libs/gitbook-2.6.7/css/style.css" rel="stylesheet" />
<link href="libs/gitbook-2.6.7/css/plugin-bookdown.css" rel="stylesheet" />
<link href="libs/gitbook-2.6.7/css/plugin-highlight.css" rel="stylesheet" />
<link href="libs/gitbook-2.6.7/css/plugin-search.css" rel="stylesheet" />
<link href="libs/gitbook-2.6.7/css/plugin-fontsettings.css" rel="stylesheet" />
<script src="https://hypothes.is/embed.js" async></script>
<link rel="stylesheet" href="css/custom.css">
<style type="text/css">
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
code > span.dt { color: #902000; } /* DataType */
code > span.dv { color: #40a070; } /* DecVal */
code > span.bn { color: #40a070; } /* BaseN */
code > span.fl { color: #40a070; } /* Float */
code > span.ch { color: #4070a0; } /* Char */
code > span.st { color: #4070a0; } /* String */
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
code > span.ot { color: #007020; } /* Other */
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
code > span.fu { color: #06287e; } /* Function */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
code > span.cn { color: #880000; } /* Constant */
code > span.sc { color: #4070a0; } /* SpecialChar */
code > span.vs { color: #4070a0; } /* VerbatimString */
code > span.ss { color: #bb6688; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { color: #19177c; } /* Variable */
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
code > span.op { color: #666666; } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #bc7a00; } /* Preprocessor */
code > span.at { color: #7d9029; } /* Attribute */
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
</style>
<link rel="stylesheet" href="css/style.css" type="text/css" />
</head>
<body>
<div class="book without-animation with-summary font-size-2 font-family-1" data-basepath=".">
<div class="book-summary">
<nav role="navigation">
<ul class="summary">
<li><a href="./">ODATE</a></li>
<li class="divider"></li>
<li class="chapter" data-level="" data-path="index.html"><a href="index.html"><i class="fa fa-check"></i>notice</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html"><i class="fa fa-check"></i>About the Authors</a><ul>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#shawn-graham"><i class="fa fa-check"></i>Shawn Graham</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#neha-gupta"><i class="fa fa-check"></i>Neha Gupta</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#michael-carter"><i class="fa fa-check"></i>Michael Carter</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#beth-compton"><i class="fa fa-check"></i>Beth Compton</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#jolene-smith"><i class="fa fa-check"></i>Jolene Smith</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#andreas-angourakis"><i class="fa fa-check"></i>Andreas Angourakis</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#andrew-reinhard"><i class="fa fa-check"></i>Andrew Reinhard</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#kate-ellenberger"><i class="fa fa-check"></i>Kate Ellenberger</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#zack-batist"><i class="fa fa-check"></i>Zack Batist</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#joel-rivard"><i class="fa fa-check"></i>Joel Rivard</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#ben-marwick"><i class="fa fa-check"></i>Ben Marwick</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#rob-blades"><i class="fa fa-check"></i>Rob Blades</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#cristina-wood"><i class="fa fa-check"></i>Cristina Wood</a></li>
<li class="chapter" data-level="" data-path="about-the-authors.html"><a href="about-the-authors.html#editorial-board"><i class="fa fa-check"></i>Editorial Board</a></li>
</ul></li>
<li class="chapter" data-level="" data-path="getting-started.html"><a href="getting-started.html"><i class="fa fa-check"></i>Getting Started</a><ul>
<li class="chapter" data-level="" data-path="instructors-how-to-use-this-text.html"><a href="instructors-how-to-use-this-text.html"><i class="fa fa-check"></i>Instructors: How to use this text</a></li>
<li class="chapter" data-level="" data-path="students-how-to-use-this-text.html"><a href="students-how-to-use-this-text.html"><i class="fa fa-check"></i>Students: How to use this text</a></li>
<li class="chapter" data-level="" data-path="how-to-contribute-changes-or-make-your-own-version.html"><a href="how-to-contribute-changes-or-make-your-own-version.html"><i class="fa fa-check"></i>How to contribute changes, or make your own version</a></li>
<li class="chapter" data-level="" data-path="how-to-access-and-use-the-computational-environment.html"><a href="how-to-access-and-use-the-computational-environment.html"><i class="fa fa-check"></i>How to access and use the computational environment</a></li>
<li class="chapter" data-level="" data-path="colophon.html"><a href="colophon.html"><i class="fa fa-check"></i>Colophon</a></li>
</ul></li>
<li class="chapter" data-level="" data-path="welcome.html"><a href="welcome.html"><i class="fa fa-check"></i>Welcome!</a></li>
<li class="chapter" data-level="1" data-path="going-digital.html"><a href="going-digital.html"><i class="fa fa-check"></i><b>1</b> Going Digital</a><ul>
<li class="chapter" data-level="1.0.1" data-path="going-digital.html"><a href="going-digital.html#further-reading"><i class="fa fa-check"></i><b>1.0.1</b> Further Reading</a></li>
<li class="chapter" data-level="1.1" data-path="so-what-is-digital-archaeology.html"><a href="so-what-is-digital-archaeology.html"><i class="fa fa-check"></i><b>1.1</b> So what is Digital Archaeology?</a><ul>
<li class="chapter" data-level="1.1.1" data-path="so-what-is-digital-archaeology.html"><a href="so-what-is-digital-archaeology.html#a-distant-view"><i class="fa fa-check"></i><b>1.1.1</b> A distant view</a></li>
<li class="chapter" data-level="1.1.2" data-path="so-what-is-digital-archaeology.html"><a href="so-what-is-digital-archaeology.html#is-digital-archaeology-part-of-the-digital-humanities"><i class="fa fa-check"></i><b>1.1.2</b> Is digital archaeology part of the digital humanities?</a></li>
<li class="chapter" data-level="1.1.3" data-path="so-what-is-digital-archaeology.html"><a href="so-what-is-digital-archaeology.html#archaeological-glitch-art"><i class="fa fa-check"></i><b>1.1.3</b> Archaeological Glitch Art</a></li>
<li class="chapter" data-level="1.1.4" data-path="so-what-is-digital-archaeology.html"><a href="so-what-is-digital-archaeology.html#the-cool-factor-and-the-tensions-of-cool"><i class="fa fa-check"></i><b>1.1.4</b> The ‘cool’ factor and the tensions of cool</a></li>
<li class="chapter" data-level="1.1.5" data-path="so-what-is-digital-archaeology.html"><a href="so-what-is-digital-archaeology.html#takeaways"><i class="fa fa-check"></i><b>1.1.5</b> Takeaways</a></li>
<li class="chapter" data-level="1.1.6" data-path="so-what-is-digital-archaeology.html"><a href="so-what-is-digital-archaeology.html#exercises"><i class="fa fa-check"></i><b>1.1.6</b> Exercises</a></li>
</ul></li>
<li class="chapter" data-level="1.2" data-path="project-management-basics.html"><a href="project-management-basics.html"><i class="fa fa-check"></i><b>1.2</b> Project Management Basics</a><ul>
<li class="chapter" data-level="1.2.1" data-path="project-management-basics.html"><a href="project-management-basics.html#take-aways"><i class="fa fa-check"></i><b>1.2.1</b> Take-aways</a></li>
<li class="chapter" data-level="1.2.2" data-path="project-management-basics.html"><a href="project-management-basics.html#exercises-1"><i class="fa fa-check"></i><b>1.2.2</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="1.3" data-path="github-version-control.html"><a href="github-version-control.html"><i class="fa fa-check"></i><b>1.3</b> Github & Version Control</a><ul>
<li class="chapter" data-level="1.3.1" data-path="github-version-control.html"><a href="github-version-control.html#the-core-functions-of-git"><i class="fa fa-check"></i><b>1.3.1</b> The core functions of Git</a></li>
<li class="chapter" data-level="1.3.2" data-path="github-version-control.html"><a href="github-version-control.html#key-terms"><i class="fa fa-check"></i><b>1.3.2</b> Key Terms</a></li>
<li class="chapter" data-level="1.3.3" data-path="github-version-control.html"><a href="github-version-control.html#take-aways-1"><i class="fa fa-check"></i><b>1.3.3</b> Take-aways</a></li>
<li class="chapter" data-level="1.3.4" data-path="github-version-control.html"><a href="github-version-control.html#further-reading-1"><i class="fa fa-check"></i><b>1.3.4</b> Further Reading</a></li>
<li class="chapter" data-level="1.3.5" data-path="github-version-control.html"><a href="github-version-control.html#exercises-2"><i class="fa fa-check"></i><b>1.3.5</b> Exercises</a></li>
<li class="chapter" data-level="1.3.6" data-path="github-version-control.html"><a href="github-version-control.html#warnings"><i class="fa fa-check"></i><b>1.3.6</b> Warnings</a></li>
</ul></li>
<li class="chapter" data-level="1.4" data-path="open-notebook-research-scholarly-communication.html"><a href="open-notebook-research-scholarly-communication.html"><i class="fa fa-check"></i><b>1.4</b> Open Notebook Research & Scholarly Communication</a><ul>
<li class="chapter" data-level="1.4.1" data-path="open-notebook-research-scholarly-communication.html"><a href="open-notebook-research-scholarly-communication.html#how-to-ask-questions"><i class="fa fa-check"></i><b>1.4.1</b> How to Ask Questions</a></li>
<li class="chapter" data-level="1.4.2" data-path="open-notebook-research-scholarly-communication.html"><a href="open-notebook-research-scholarly-communication.html#discussion"><i class="fa fa-check"></i><b>1.4.2</b> discussion</a></li>
<li class="chapter" data-level="1.4.3" data-path="open-notebook-research-scholarly-communication.html"><a href="open-notebook-research-scholarly-communication.html#take-aways-2"><i class="fa fa-check"></i><b>1.4.3</b> Take-aways</a></li>
<li class="chapter" data-level="1.4.4" data-path="open-notebook-research-scholarly-communication.html"><a href="open-notebook-research-scholarly-communication.html#further-reading-2"><i class="fa fa-check"></i><b>1.4.4</b> Further Reading</a></li>
<li class="chapter" data-level="1.4.5" data-path="open-notebook-research-scholarly-communication.html"><a href="open-notebook-research-scholarly-communication.html#on-privilege-and-open-notebooks"><i class="fa fa-check"></i><b>1.4.5</b> On Privilege and Open Notebooks</a></li>
<li class="chapter" data-level="1.4.6" data-path="open-notebook-research-scholarly-communication.html"><a href="open-notebook-research-scholarly-communication.html#exercises-3"><i class="fa fa-check"></i><b>1.4.6</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="1.5" data-path="failing-productively.html"><a href="failing-productively.html"><i class="fa fa-check"></i><b>1.5</b> Failing Productively</a><ul>
<li class="chapter" data-level="1.5.1" data-path="failing-productively.html"><a href="failing-productively.html#a-taxonomy-of-fails"><i class="fa fa-check"></i><b>1.5.1</b> A taxonomy of fails</a></li>
<li class="chapter" data-level="1.5.2" data-path="failing-productively.html"><a href="failing-productively.html#exercises-4"><i class="fa fa-check"></i><b>1.5.2</b> Exercises</a></li>
</ul></li>
<li class="chapter" data-level="1.6" data-path="the-ethics-of-big-data-in-archaeology.html"><a href="the-ethics-of-big-data-in-archaeology.html"><i class="fa fa-check"></i><b>1.6</b> The Ethics of Big Data in Archaeology</a><ul>
<li class="chapter" data-level="1.6.1" data-path="the-ethics-of-big-data-in-archaeology.html"><a href="the-ethics-of-big-data-in-archaeology.html#exercises-5"><i class="fa fa-check"></i><b>1.6.1</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="1.7" data-path="effective-collaboration.html"><a href="effective-collaboration.html"><i class="fa fa-check"></i><b>1.7</b> Effective Collaboration</a><ul>
<li class="chapter" data-level="1.7.1" data-path="effective-collaboration.html"><a href="effective-collaboration.html#the-two-sentence-pitch"><i class="fa fa-check"></i><b>1.7.1</b> The Two-Sentence Pitch</a></li>
<li class="chapter" data-level="1.7.2" data-path="effective-collaboration.html"><a href="effective-collaboration.html#consulting-colleagues-and-stakeholders"><i class="fa fa-check"></i><b>1.7.2</b> Consulting Colleagues and Stakeholders</a></li>
<li class="chapter" data-level="1.7.3" data-path="effective-collaboration.html"><a href="effective-collaboration.html#making-a-plan"><i class="fa fa-check"></i><b>1.7.3</b> Making a Plan</a></li>
<li class="chapter" data-level="1.7.4" data-path="effective-collaboration.html"><a href="effective-collaboration.html#persisting-and-adapting-your-plan"><i class="fa fa-check"></i><b>1.7.4</b> Persisting and Adapting your Plan</a></li>
<li class="chapter" data-level="1.7.5" data-path="effective-collaboration.html"><a href="effective-collaboration.html#exercises-6"><i class="fa fa-check"></i><b>1.7.5</b> Exercises</a></li>
</ul></li>
</ul></li>
<li class="chapter" data-level="2" data-path="making-data-useful.html"><a href="making-data-useful.html"><i class="fa fa-check"></i><b>2</b> Making Data Useful</a><ul>
<li class="chapter" data-level="2.1" data-path="proper-prior-planning.html"><a href="proper-prior-planning.html"><i class="fa fa-check"></i><b>2.1</b> Proper Prior Planning</a><ul>
<li class="chapter" data-level="2.1.1" data-path="proper-prior-planning.html"><a href="proper-prior-planning.html#making-data-sensible-pre-planning"><i class="fa fa-check"></i><b>2.1.1</b> Making Data Sensible: Pre-Planning</a></li>
<li class="chapter" data-level="2.1.2" data-path="proper-prior-planning.html"><a href="proper-prior-planning.html#making-data-durable-preservation-and-longevity"><i class="fa fa-check"></i><b>2.1.2</b> Making Data Durable: Preservation and Longevity</a></li>
<li class="chapter" data-level="2.1.3" data-path="proper-prior-planning.html"><a href="proper-prior-planning.html#takeaways-1"><i class="fa fa-check"></i><b>2.1.3</b> Takeaways</a></li>
<li class="chapter" data-level="2.1.4" data-path="proper-prior-planning.html"><a href="proper-prior-planning.html#further-reading-3"><i class="fa fa-check"></i><b>2.1.4</b> Further Reading</a></li>
</ul></li>
<li class="chapter" data-level="2.2" data-path="designing-data-collection-and-curation.html"><a href="designing-data-collection-and-curation.html"><i class="fa fa-check"></i><b>2.2</b> Designing Data Collection and Curation</a><ul>
<li class="chapter" data-level="2.2.1" data-path="designing-data-collection-and-curation.html"><a href="designing-data-collection-and-curation.html#takeaways-2"><i class="fa fa-check"></i><b>2.2.1</b> Takeaways</a></li>
<li class="chapter" data-level="2.2.2" data-path="designing-data-collection-and-curation.html"><a href="designing-data-collection-and-curation.html#further-reading-4"><i class="fa fa-check"></i><b>2.2.2</b> Further Reading</a></li>
</ul></li>
<li class="chapter" data-level="2.3" data-path="cleaning-data.html"><a href="cleaning-data.html"><i class="fa fa-check"></i><b>2.3</b> Cleaning Data</a><ul>
<li class="chapter" data-level="2.3.1" data-path="cleaning-data.html"><a href="cleaning-data.html#tools"><i class="fa fa-check"></i><b>2.3.1</b> Tools</a></li>
<li class="chapter" data-level="2.3.2" data-path="cleaning-data.html"><a href="cleaning-data.html#cleaning-tasks"><i class="fa fa-check"></i><b>2.3.2</b> Cleaning Tasks</a></li>
<li class="chapter" data-level="2.3.3" data-path="cleaning-data.html"><a href="cleaning-data.html#takeaways-3"><i class="fa fa-check"></i><b>2.3.3</b> Takeaways</a></li>
<li class="chapter" data-level="2.3.4" data-path="cleaning-data.html"><a href="cleaning-data.html#further-reading-5"><i class="fa fa-check"></i><b>2.3.4</b> Further Reading</a></li>
</ul></li>
<li class="chapter" data-level="2.4" data-path="arranging-and-storing-data-for-the-long-haul-databases.html"><a href="arranging-and-storing-data-for-the-long-haul-databases.html"><i class="fa fa-check"></i><b>2.4</b> Arranging and Storing Data for the Long Haul (Databases!)</a><ul>
<li class="chapter" data-level="" data-path="arranging-and-storing-data-for-the-long-haul-databases.html"><a href="arranging-and-storing-data-for-the-long-haul-databases.html#flat-tables"><i class="fa fa-check"></i>Flat tables</a></li>
<li class="chapter" data-level="2.4.1" data-path="arranging-and-storing-data-for-the-long-haul-databases.html"><a href="arranging-and-storing-data-for-the-long-haul-databases.html#takeaways-4"><i class="fa fa-check"></i><b>2.4.1</b> Takeaways</a></li>
<li class="chapter" data-level="2.4.2" data-path="arranging-and-storing-data-for-the-long-haul-databases.html"><a href="arranging-and-storing-data-for-the-long-haul-databases.html#further-reading-6"><i class="fa fa-check"></i><b>2.4.2</b> Further Reading</a></li>
<li class="chapter" data-level="2.4.3" data-path="arranging-and-storing-data-for-the-long-haul-databases.html"><a href="arranging-and-storing-data-for-the-long-haul-databases.html#exercises-7"><i class="fa fa-check"></i><b>2.4.3</b> Exercises</a></li>
</ul></li>
<li class="chapter" data-level="2.5" data-path="linked-open-data-and-data-publishing.html"><a href="linked-open-data-and-data-publishing.html"><i class="fa fa-check"></i><b>2.5</b> Linked Open Data and Data Publishing</a></li>
<li class="chapter" data-level="2.6" data-path="using-application-programming-interfaces-apis-to-retrieve-data.html"><a href="using-application-programming-interfaces-apis-to-retrieve-data.html"><i class="fa fa-check"></i><b>2.6</b> Using Application Programming Interfaces (APIS) to Retrieve Data</a><ul>
<li class="chapter" data-level="2.6.1" data-path="using-application-programming-interfaces-apis-to-retrieve-data.html"><a href="using-application-programming-interfaces-apis-to-retrieve-data.html#exercises-8"><i class="fa fa-check"></i><b>2.6.1</b> Exercises</a></li>
</ul></li>
<li class="chapter" data-level="2.7" data-path="scraping-data.html"><a href="scraping-data.html"><i class="fa fa-check"></i><b>2.7</b> Scraping Data</a><ul>
<li class="chapter" data-level="2.7.1" data-path="scraping-data.html"><a href="scraping-data.html#exercises-9"><i class="fa fa-check"></i><b>2.7.1</b> Exercises</a></li>
</ul></li>
</ul></li>
<li class="chapter" data-level="3" data-path="finding-and-communicating-the-compelling-story.html"><a href="finding-and-communicating-the-compelling-story.html"><i class="fa fa-check"></i><b>3</b> Finding and Communicating the Compelling Story</a><ul>
<li class="chapter" data-level="3.1" data-path="designing-for-accessibility.html"><a href="designing-for-accessibility.html"><i class="fa fa-check"></i><b>3.1</b> Designing for Accessibility</a><ul>
<li class="chapter" data-level="3.1.1" data-path="designing-for-accessibility.html"><a href="designing-for-accessibility.html#screen-readers-text-browsers-html-labels-and-headings"><i class="fa fa-check"></i><b>3.1.1</b> Screen Readers, Text Browsers, HTML Labels, and Headings</a></li>
<li class="chapter" data-level="3.1.2" data-path="designing-for-accessibility.html"><a href="designing-for-accessibility.html#contrast-and-styles"><i class="fa fa-check"></i><b>3.1.2</b> Contrast and Styles</a></li>
<li class="chapter" data-level="3.1.3" data-path="designing-for-accessibility.html"><a href="designing-for-accessibility.html#font"><i class="fa fa-check"></i><b>3.1.3</b> Font</a></li>
<li class="chapter" data-level="3.1.4" data-path="designing-for-accessibility.html"><a href="designing-for-accessibility.html#going-forward"><i class="fa fa-check"></i><b>3.1.4</b> Going Forward</a></li>
<li class="chapter" data-level="3.1.5" data-path="designing-for-accessibility.html"><a href="designing-for-accessibility.html#exercises-10"><i class="fa fa-check"></i><b>3.1.5</b> Exercises</a></li>
<li class="chapter" data-level="3.1.6" data-path="designing-for-accessibility.html"><a href="designing-for-accessibility.html#further-reading-7"><i class="fa fa-check"></i><b>3.1.6</b> Further Reading</a></li>
</ul></li>
<li class="chapter" data-level="3.2" data-path="statistical-computing-with-r-and-python-notebooks-reproducible-code.html"><a href="statistical-computing-with-r-and-python-notebooks-reproducible-code.html"><i class="fa fa-check"></i><b>3.2</b> Statistical Computing with R and Python Notebooks; Reproducible code</a><ul>
<li class="chapter" data-level="3.2.1" data-path="statistical-computing-with-r-and-python-notebooks-reproducible-code.html"><a href="statistical-computing-with-r-and-python-notebooks-reproducible-code.html#reproducible-methods"><i class="fa fa-check"></i><b>3.2.1</b> Reproducible Methods</a></li>
<li class="chapter" data-level="3.2.2" data-path="statistical-computing-with-r-and-python-notebooks-reproducible-code.html"><a href="statistical-computing-with-r-and-python-notebooks-reproducible-code.html#exercises-11"><i class="fa fa-check"></i><b>3.2.2</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="3.3" data-path="data-driven-documents.html"><a href="data-driven-documents.html"><i class="fa fa-check"></i><b>3.3</b> Data Driven Documents</a><ul>
<li class="chapter" data-level="3.3.1" data-path="data-driven-documents.html"><a href="data-driven-documents.html#d3"><i class="fa fa-check"></i><b>3.3.1</b> D3</a></li>
<li class="chapter" data-level="3.3.2" data-path="data-driven-documents.html"><a href="data-driven-documents.html#discussion-1"><i class="fa fa-check"></i><b>3.3.2</b> discussion</a></li>
<li class="chapter" data-level="3.3.3" data-path="data-driven-documents.html"><a href="data-driven-documents.html#exercises-12"><i class="fa fa-check"></i><b>3.3.3</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="3.4" data-path="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html"><a href="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html"><i class="fa fa-check"></i><b>3.4</b> Storytelling and the Archaeological CMS: Omeka, Kora, and Mukurtu</a><ul>
<li class="chapter" data-level="3.4.1" data-path="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html"><a href="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html#the-content-management-system"><i class="fa fa-check"></i><b>3.4.1</b> The Content Management System</a></li>
<li class="chapter" data-level="3.4.2" data-path="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html"><a href="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html#omeka"><i class="fa fa-check"></i><b>3.4.2</b> Omeka</a></li>
<li class="chapter" data-level="3.4.3" data-path="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html"><a href="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html#kora"><i class="fa fa-check"></i><b>3.4.3</b> Kora</a></li>
<li class="chapter" data-level="3.4.4" data-path="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html"><a href="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html#mukurtu"><i class="fa fa-check"></i><b>3.4.4</b> Mukurtu</a></li>
<li class="chapter" data-level="3.4.5" data-path="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html"><a href="storytelling-and-the-archaeological-cms-omeka-kora-and-mukurtu.html#exercises-13"><i class="fa fa-check"></i><b>3.4.5</b> Exercises</a></li>
</ul></li>
<li class="chapter" data-level="3.5" data-path="what-is-web-mapping.html"><a href="what-is-web-mapping.html"><i class="fa fa-check"></i><b>3.5</b> What is Web Mapping?</a><ul>
<li class="chapter" data-level="3.5.1" data-path="what-is-web-mapping.html"><a href="what-is-web-mapping.html#overview-of-map-services"><i class="fa fa-check"></i><b>3.5.1</b> Overview of Map Services</a></li>
<li class="chapter" data-level="3.5.2" data-path="what-is-web-mapping.html"><a href="what-is-web-mapping.html#making-a-web-map-with-leaflet"><i class="fa fa-check"></i><b>3.5.2</b> Making a web map with Leaflet</a></li>
<li class="chapter" data-level="3.5.3" data-path="what-is-web-mapping.html"><a href="what-is-web-mapping.html#exercises-14"><i class="fa fa-check"></i><b>3.5.3</b> Exercises</a></li>
<li class="chapter" data-level="3.5.4" data-path="what-is-web-mapping.html"><a href="what-is-web-mapping.html#resources"><i class="fa fa-check"></i><b>3.5.4</b> Resources</a></li>
</ul></li>
<li class="chapter" data-level="3.6" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html"><i class="fa fa-check"></i><b>3.6</b> Virtual Archaeology</a><ul>
<li class="chapter" data-level="3.6.1" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html#basic-principles"><i class="fa fa-check"></i><b>3.6.1</b> Basic principles</a></li>
<li class="chapter" data-level="3.6.2" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html#main-challenge"><i class="fa fa-check"></i><b>3.6.2</b> Main Challenge</a></li>
<li class="chapter" data-level="3.6.3" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html#the-archaeological-narrative"><i class="fa fa-check"></i><b>3.6.3</b> The Archaeological Narrative</a></li>
<li class="chapter" data-level="3.6.4" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html#theoretical-pragmatism"><i class="fa fa-check"></i><b>3.6.4</b> Theoretical Pragmatism</a></li>
<li class="chapter" data-level="3.6.5" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html#phenomenology-and-virtual-archaeology"><i class="fa fa-check"></i><b>3.6.5</b> Phenomenology and Virtual Archaeology</a></li>
<li class="chapter" data-level="3.6.6" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html#lasting-considerations"><i class="fa fa-check"></i><b>3.6.6</b> Lasting Considerations</a></li>
<li class="chapter" data-level="3.6.7" data-path="virtual-archaeology.html"><a href="virtual-archaeology.html#exercises-15"><i class="fa fa-check"></i><b>3.6.7</b> Exercises</a></li>
</ul></li>
<li class="chapter" data-level="3.7" data-path="archaeogaming.html"><a href="archaeogaming.html"><i class="fa fa-check"></i><b>3.7</b> Archaeogaming</a><ul>
<li class="chapter" data-level="3.7.1" data-path="archaeogaming.html"><a href="archaeogaming.html#archaeological-reception"><i class="fa fa-check"></i><b>3.7.1</b> Archaeological Reception</a></li>
<li class="chapter" data-level="3.7.2" data-path="archaeogaming.html"><a href="archaeogaming.html#games-as-archaeology"><i class="fa fa-check"></i><b>3.7.2</b> Games as Archaeology</a></li>
<li class="chapter" data-level="3.7.3" data-path="archaeogaming.html"><a href="archaeogaming.html#archaeogaming-projects-past-and-present"><i class="fa fa-check"></i><b>3.7.3</b> Archaeogaming Projects Past and Present</a></li>
<li class="chapter" data-level="3.7.4" data-path="archaeogaming.html"><a href="archaeogaming.html#is-archaeogaming-archaeology-a-future-of-the-discipline."><i class="fa fa-check"></i><b>3.7.4</b> Is Archaeogaming Archaeology? A Future of the Discipline.</a></li>
<li class="chapter" data-level="3.7.5" data-path="archaeogaming.html"><a href="archaeogaming.html#exercises-16"><i class="fa fa-check"></i><b>3.7.5</b> Exercises</a></li>
<li class="chapter" data-level="3.7.6" data-path="archaeogaming.html"><a href="archaeogaming.html#further-reading-8"><i class="fa fa-check"></i><b>3.7.6</b> Further Reading</a></li>
</ul></li>
<li class="chapter" data-level="3.8" data-path="social-media-as-public-engagement-scholarly-communication-in-archaeology.html"><a href="social-media-as-public-engagement-scholarly-communication-in-archaeology.html"><i class="fa fa-check"></i><b>3.8</b> Social Media as Public Engagement & Scholarly Communication in Archaeology</a><ul>
<li class="chapter" data-level="3.8.1" data-path="social-media-as-public-engagement-scholarly-communication-in-archaeology.html"><a href="social-media-as-public-engagement-scholarly-communication-in-archaeology.html#social-media-as-outreach"><i class="fa fa-check"></i><b>3.8.1</b> Social Media as Outreach</a></li>
<li class="chapter" data-level="3.8.2" data-path="social-media-as-public-engagement-scholarly-communication-in-archaeology.html"><a href="social-media-as-public-engagement-scholarly-communication-in-archaeology.html#social-media-to-keep-current-on-research"><i class="fa fa-check"></i><b>3.8.2</b> Social Media to Keep Current on Research</a></li>
<li class="chapter" data-level="3.8.3" data-path="social-media-as-public-engagement-scholarly-communication-in-archaeology.html"><a href="social-media-as-public-engagement-scholarly-communication-in-archaeology.html#four-moves-or-getting-at-the-truth"><i class="fa fa-check"></i><b>3.8.3</b> Four Moves, or, Getting at the Truth</a></li>
<li class="chapter" data-level="3.8.4" data-path="social-media-as-public-engagement-scholarly-communication-in-archaeology.html"><a href="social-media-as-public-engagement-scholarly-communication-in-archaeology.html#exercises-17"><i class="fa fa-check"></i><b>3.8.4</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="3.9" data-path="computational-creativity.html"><a href="computational-creativity.html"><i class="fa fa-check"></i><b>3.9</b> Computational Creativity</a><ul>
<li class="chapter" data-level="3.9.1" data-path="computational-creativity.html"><a href="computational-creativity.html#twitterbots-with-tracery"><i class="fa fa-check"></i><b>3.9.1</b> Twitterbots with Tracery</a></li>
<li class="chapter" data-level="3.9.2" data-path="computational-creativity.html"><a href="computational-creativity.html#chatbots"><i class="fa fa-check"></i><b>3.9.2</b> Chatbots</a></li>
<li class="chapter" data-level="3.9.3" data-path="computational-creativity.html"><a href="computational-creativity.html#sonification"><i class="fa fa-check"></i><b>3.9.3</b> Sonification</a></li>
<li class="chapter" data-level="3.9.4" data-path="computational-creativity.html"><a href="computational-creativity.html#worldbuilding"><i class="fa fa-check"></i><b>3.9.4</b> Worldbuilding</a></li>
</ul></li>
</ul></li>
<li class="chapter" data-level="4" data-path="eliding-the-digital-and-the-physical.html"><a href="eliding-the-digital-and-the-physical.html"><i class="fa fa-check"></i><b>4</b> Eliding the Digital and the Physical</a><ul>
<li class="chapter" data-level="4.1" data-path="d-photogrammetry.html"><a href="d-photogrammetry.html"><i class="fa fa-check"></i><b>4.1</b> 3D Photogrammetry</a><ul>
<li class="chapter" data-level="4.1.1" data-path="d-photogrammetry.html"><a href="d-photogrammetry.html#basic-principles-1"><i class="fa fa-check"></i><b>4.1.1</b> Basic principles</a></li>
<li class="chapter" data-level="4.1.2" data-path="d-photogrammetry.html"><a href="d-photogrammetry.html#further-readings"><i class="fa fa-check"></i><b>4.1.2</b> Further Readings</a></li>
<li class="chapter" data-level="4.1.3" data-path="d-photogrammetry.html"><a href="d-photogrammetry.html#exercises-19"><i class="fa fa-check"></i><b>4.1.3</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="4.2" data-path="d-printing-raspberry-pi-and-maker-archaeology.html"><a href="d-printing-raspberry-pi-and-maker-archaeology.html"><i class="fa fa-check"></i><b>4.2</b> 3D Printing, Raspberry Pi and “Maker” Archaeology</a><ul>
<li class="chapter" data-level="4.2.1" data-path="d-printing-raspberry-pi-and-maker-archaeology.html"><a href="d-printing-raspberry-pi-and-maker-archaeology.html#overview"><i class="fa fa-check"></i><b>4.2.1</b> Overview</a></li>
<li class="chapter" data-level="4.2.2" data-path="d-printing-raspberry-pi-and-maker-archaeology.html"><a href="d-printing-raspberry-pi-and-maker-archaeology.html#d-printing---a-workflow"><i class="fa fa-check"></i><b>4.2.2</b> 3d Printing - a Workflow</a></li>
<li class="chapter" data-level="4.2.3" data-path="d-printing-raspberry-pi-and-maker-archaeology.html"><a href="d-printing-raspberry-pi-and-maker-archaeology.html#using-raspberry-pi-in-the-field"><i class="fa fa-check"></i><b>4.2.3</b> Using Raspberry Pi in the Field</a></li>
<li class="chapter" data-level="4.2.4" data-path="d-printing-raspberry-pi-and-maker-archaeology.html"><a href="d-printing-raspberry-pi-and-maker-archaeology.html#discussion-2"><i class="fa fa-check"></i><b>4.2.4</b> Discussion</a></li>
<li class="chapter" data-level="4.2.5" data-path="d-printing-raspberry-pi-and-maker-archaeology.html"><a href="d-printing-raspberry-pi-and-maker-archaeology.html#further-reading-9"><i class="fa fa-check"></i><b>4.2.5</b> Further Reading</a></li>
</ul></li>
<li class="chapter" data-level="4.3" data-path="place-based-interpretation-with-locative-augmented-reality.html"><a href="place-based-interpretation-with-locative-augmented-reality.html"><i class="fa fa-check"></i><b>4.3</b> Place-based Interpretation with Locative Augmented Reality</a><ul>
<li class="chapter" data-level="4.3.1" data-path="place-based-interpretation-with-locative-augmented-reality.html"><a href="place-based-interpretation-with-locative-augmented-reality.html#projection-mapping"><i class="fa fa-check"></i><b>4.3.1</b> Projection Mapping</a></li>
<li class="chapter" data-level="4.3.2" data-path="place-based-interpretation-with-locative-augmented-reality.html"><a href="place-based-interpretation-with-locative-augmented-reality.html#exercises-20"><i class="fa fa-check"></i><b>4.3.2</b> exercises</a></li>
</ul></li>
<li class="chapter" data-level="4.4" data-path="artificial-intelligence-in-digital-archaeology.html"><a href="artificial-intelligence-in-digital-archaeology.html"><i class="fa fa-check"></i><b>4.4</b> Artificial Intelligence in Digital Archaeology</a><ul>
<li class="chapter" data-level="4.4.1" data-path="artificial-intelligence-in-digital-archaeology.html"><a href="artificial-intelligence-in-digital-archaeology.html#agent-based-modeling-abm"><i class="fa fa-check"></i><b>4.4.1</b> Agent-based modeling (ABM)</a></li>
</ul></li>
<li class="chapter" data-level="4.5" data-path="computer-vision-and-archaeology.html"><a href="computer-vision-and-archaeology.html"><i class="fa fa-check"></i><b>4.5</b> Computer Vision and Archaeology</a><ul>
<li class="chapter" data-level="4.5.1" data-path="computer-vision-and-archaeology.html"><a href="computer-vision-and-archaeology.html#convolutional-neural-networks"><i class="fa fa-check"></i><b>4.5.1</b> Convolutional Neural Networks</a></li>
<li class="chapter" data-level="4.5.2" data-path="computer-vision-and-archaeology.html"><a href="computer-vision-and-archaeology.html#applications"><i class="fa fa-check"></i><b>4.5.2</b> Applications</a></li>
<li class="chapter" data-level="4.5.3" data-path="computer-vision-and-archaeology.html"><a href="computer-vision-and-archaeology.html#exercises-21"><i class="fa fa-check"></i><b>4.5.3</b> Exercises</a></li>
</ul></li>
</ul></li>
<li class="chapter" data-level="5" data-path="digital-archaeologys-place-in-the-world.html"><a href="digital-archaeologys-place-in-the-world.html"><i class="fa fa-check"></i><b>5</b> Digital Archaeology’s Place in the World</a><ul>
<li class="chapter" data-level="5.1" data-path="marketing-digital-archaeology.html"><a href="marketing-digital-archaeology.html"><i class="fa fa-check"></i><b>5.1</b> Marketing Digital Archaeology</a></li>
<li class="chapter" data-level="5.2" data-path="sustainability-power-in-digital-archaeology.html"><a href="sustainability-power-in-digital-archaeology.html"><i class="fa fa-check"></i><b>5.2</b> Sustainability & Power in Digital Archaeology</a><ul>
<li class="chapter" data-level="5.2.1" data-path="sustainability-power-in-digital-archaeology.html"><a href="sustainability-power-in-digital-archaeology.html#exercises-22"><i class="fa fa-check"></i><b>5.2.1</b> exercises</a></li>
</ul></li>
</ul></li>
<li class="chapter" data-level="6" data-path="on-the-horizons-where-digital-archaeology-might-go-next.html"><a href="on-the-horizons-where-digital-archaeology-might-go-next.html"><i class="fa fa-check"></i><b>6</b> On the Horizons: Where Digital Archaeology Might Go Next</a></li>
<li class="chapter" data-level="" data-path="references.html"><a href="references.html"><i class="fa fa-check"></i>References</a></li>
<li class="divider"></li>
<li><a href="https://creativecommons.org/licenses/by/4.0/" target="blank">CC-BY 4.0</a></li>
<li><a href="https://github.com/rstudio/bookdown" target="blank">Made with bookdown</a></li>
<li><a href="https://www.ecampusontario.ca/" target="blank">Funded by EcampusOntario</a></li>
</ul>
</nav>
</div>
<div class="book-body">
<div class="body-inner">
<div class="book-header" role="navigation">
<h1>
<i class="fa fa-circle-o-notch fa-spin"></i><a href="./">The Open Digital Archaeology Textbook</a>
</h1>
</div>
<div class="page-wrapper" tabindex="-1" role="main">
<div class="page-inner">
<section class="normal" id="section-">
<div id="github-version-control" class="section level2">
<h2><span class="header-section-number">1.3</span> Github & Version Control</h2>
<div class="rmdnote">
<em><a href="https://github.com/o-date/notebooks/">Launch a simple notebook</a>.</em>
</div>
<p>It’s a familiar situation - you’ve been working on a paper. It’s where you want it to be, and you’re certain you’re done. You save it as ‘final.doc’. Then, you ask your friend to take a look at it. She spots several typos and that you flubbed an entire paragraph. You open it up, make the changes, and save as ‘final-w-changes.doc’. Later that day it occurs to you that you don’t like those changes, and you go back to the original ‘final.doc’, make some changes, and just overwrite the previous version. Soon, you have a folder like:</p>
<div class="sourceCode"><pre class="sourceCode fortran"><code class="sourceCode fortran"><span class="kw">|-</span>project
<span class="kw">|-</span><span class="st">'finalfinal.doc'</span>
<span class="kw">|-</span><span class="st">'final-w-changes.doc'</span>
<span class="kw">|-</span><span class="st">'final-w-changes2.doc'</span>
<span class="kw">|-</span><span class="st">'isthisone-changes.doc'</span>
<span class="kw">|-</span><span class="st">'this.doc'</span></code></pre></div>
<p>Things can get messy quite quickly. Imagine that you also have several spreadsheets in there as well, images, snippets of code… we don’t want this. What we want is a way of managing the evolution of your files. We do this with a program called <a href="https://git-scm.com/">Git</a>. Git is not a user-friendly piece of software, and it takes some work to get your head around. Git is also very powerful, but fortunately, the basic uses to which most of us put it to are more or less straightforward. There are many other programs that make use of Git for version control; these programs weld a graphical user interface on top of the main Git program. It is better however to become familiar with the basic uses of git from the command line <em>first</em> before learning the idiosyncrasies of these helper programs. The exercises in this section will take you through the basics of using Git from the command line.</p>
<div id="the-core-functions-of-git" class="section level3">
<h3><span class="header-section-number">1.3.1</span> The core functions of Git</h3>
<p>At its heart, Git is a way of taking ‘snapshots’ of the current state of a folder, and saving those snapshots or versions in sequence. For an excellent brief presentation on Git, see Alice Bartlett’s <a href="https://speakerdeck.com/alicebartlett/git-for-humans">presentation here</a>. In Git’s lingo, a folder on your computer is known as a <code>repository</code>. This sequence of versions in total lets you see how your project unfolded over time. Each time you wish to take a version, you make a <code>commit</code>. A commit is a Git command to take a snapshot of the entire repository. Thus, your folder we discussed above, with its proliferation of documents becomes:</p>
<div class="sourceCode"><pre class="sourceCode fortran"><code class="sourceCode fortran"><span class="kw">|-</span>project
<span class="kw">|-</span><span class="st">'final.doc'</span></code></pre></div>
<p>BUT its commit history could be visualized like this:</p>
<div class="figure">
<img src="images/commit-history.png" alt="A visualization of the history of commits" />
<p class="caption">A visualization of the history of commits</p>
</div>
<p>Each one of those circles represents a point in time when you the writer made a commit; Git compared the state of the file to the earlier state, and saved a snapshot of the <code>differences</code>. What is particularly useful about making a commit is that Git requires two more pieces of information about the git: who is making it, and when. The final useful bit about a commit is that you can save a detailed message about <em>why</em> the commit is being made. In our hypothetical situation, your first commit message might look like this:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">Fixed</span> conclusion
<span class="kw">Julie</span> pointed out that I had missed
<span class="kw">the</span> critical bit in the assignment
<span class="kw">regarding</span> stratigraphy. This was
<span class="kw">added</span> in the concluding section.</code></pre></div>
<p>This information is stored in the history of the commits. In this way, you can see exactly how the project evolved and why. Each one of these commits has what is called a <code>hash</code>. This is a unique fingerprint that you can use to ‘time travel’ (to borrow Bartlett’s phrasing). If you want to see what your project looked like a few months ago, you <code>checkout</code> that commit. This has the effect of ‘rewinding’ the project. Once you’ve checked out a commit, don’t be alarmed when you look at the folder: your folder (your repository) looks like how it once did all those weeks ago! Any files written after that commit seem as if they’ve disappeared. Don’t worry: they still exist!</p>
<p>What would happen if you wanted to experiment or take your project in a new direction from that point forward? Git lets you do this. What you will do is create a new <code>branch</code> of your project from that point. You can think of a branch as like the branch of a tree, or perhaps better, a branch of a river that eventually merges back to the source. Another way of thinking about a branch is that it is a label that sticks with these particular commits. It is generally considered ‘best practice’ to leave your <code>master</code> branch alone, in the sense that it represents the best version of your project. When you want to experiment or do something new, you create a <code>branch</code> and work there. If the work on the branch ultimately proves fruitless, you can discard it. <em>But</em>, if you decide that you like how it’s going, you can <code>merge</code> that branch back into your master. A merge is a commit that folds all of the commits from the branch with the commits from the master.</p>
<p>Git is also a powerful tool for backing up your work. You can work quite happily with Git on your own machine, but when you store those files and the history of commits somewhere remote, you open up the possibility of collaboration <em>and</em> a safe place where your materials can be recalled if -perish the thought- something happened to your computer. In Git-speak, the remote location is, well, the <code>remote</code>. There are many different places on the web that can function as a remote for Git repositories. You can even set one up on your own server, if you want. One of the most popular (and the one that we use for ODATE) is <a href="http://github.com">Github</a>. There are many useful repositories shared via Github of interest to archaeologists - <a href="http://opencontext.org">OpenContext</a> for instance shares a lot of material that way. To get material <em>out</em> of Github and onto your own computer, you <code>clone</code> it. If that hypothetical paper you were writing was part of a group project, your partners could clone it from your Github space, and work on it as well!</p>
<p>You and Anna are working together on the project. You have made a new project repository in your Github space, and you have cloned it to your computer. Anna has cloned it to hers. Let’s assume that you have a very productive weekend and you make some real headway on the project. You <code>commit</code> your changes, and then <code>push</code> them from your computer to the Github version of your repository. That repository is now one commit <em>ahead</em> of Anna’s version. Anna <code>pulls</code> those changes from Github to her own version of the repository, which now looks <em>exactly</em> like your version. What happens if you make changes to the exact same part of the exact same file? This is called a <code>conflict</code>. Git will make a version of the file that contains text clearly marking off the part of the file where the conflict occurs, with the conflicting information marked out as well. The way to <code>resolve</code> the conflict is to open the file (typically with a text editor) and to delete the added Git text, making a decision on which information is the correct information.</p>
</div>
<div id="key-terms" class="section level3">
<h3><span class="header-section-number">1.3.2</span> Key Terms</h3>
<ul>
<li>repository: a single folder that holds all of the files and subfolders of your project</li>
<li>commit: this means, ‘take a snapshot of the current state of my repository’</li>
<li>publish: take my folder on my computer, and copy it and its contents to the web as a repository at github.com/myusername/repositoryname</li>
<li>sync: update the web repository with the latest commit from my local folder</li>
<li>branch: make a copy of my repository with a ‘working name’</li>
<li>merge: fold the changes I have made on a branch into another branch</li>
<li>fork: to make a copy of someone else’s repo</li>
<li>clone: to copy an online repo onto your own computer</li>
<li>pull request: to ask the original maker of a repo to ‘pull’ your changes into their master, original, repository</li>
<li>push: to move your changes from your computer to the online repo</li>
<li>conflict: when two commits describe different changes to the same part of a file</li>
</ul>
</div>
<div id="take-aways-1" class="section level3">
<h3><span class="header-section-number">1.3.3</span> Take-aways</h3>
<ul>
<li>Git keeps track of all of the differences in your files, when you take a ‘snapshot’ of the state of your folder (repository) with the <code>commit</code> command</li>
<li>Git allows you to roll back changes</li>
<li>Git allows you to experiment by making changes that can be deleted or incorporated as desired</li>
<li>Git allows you to manage collaboration safely</li>
<li>Git allows you to distribute your materials</li>
</ul>
</div>
<div id="further-reading-1" class="section level3">
<h3><span class="header-section-number">1.3.4</span> Further Reading</h3>
<p>We alluded above to the presence of ‘helper’ programs that are designed to make it easier to use Git to its full potential. An excellent introduction to Github’s desktop GUI is at this <a href="http://programminghistorian.org/lessons/getting-started-with-github-desktop">Programming Historian lesson on Github</a>. A follow-up lesson explains the way Github itself can be used to host entire websites! You may explore it <a href="http://programminghistorian.org/lessons/building-static-sites-with-jekyll-github-pages">here</a>. In the section of this chapter on open notebooks, we will also use Git and Github to create a simple open notebook for your research projects.</p>
<p>You might also wish to dip into the <a href="https://www.youtube.com/watch?v=D0_j04BnVeA">archived live stream; link here</a> from the first day of the NEH funded Institute on Digital Archaeology Method and Practice (2015) where Prof. Ethan Watrall discusses project management fundamentals and, towards the last part of the stream, introduces Git.</p>
</div>
<div id="exercises-2" class="section level3">
<h3><span class="header-section-number">1.3.5</span> Exercises</h3>
<p>Take a copy of the <a href="https://github.com/o-date/notebooks/">ODATE Binder</a>. Carefully peruse the <a href="https://github.com/o-date/notebooks/blob/master/README.md">readme</a> so that you can create your own version of the <em>executable</em> version. Once you’ve done that, launch the binder. It might take five or six minutes to launch; be patient.</p>
<p>Once it has launched, click the <code>new</code> dropdown and select terminal.</p>
<ol style="list-style-type: decimal">
<li>Because the Jupyter notebook is being served from a github repository, the <code>git</code> program is already running in the background and is keeping track of changes. If you were working on your own machine (and had git installed), you could turn <em>any</em> folder into a repository by telling Git to start watching the folder, by typing <code>git init</code> at the command prompt inside that folder.</li>
</ol>
<p>Periodically, we tell Git to take a snapshot of the state of the files in the folder by using the command ‘git commit’. This sequence of changes to your repo are stored in a <em>hidden</em> directory, <code>.git</code>. Most of the time, you will never have reason to search that folder out. (But know that the config file that describes your repo is in that folder. There might come a time in the future where you want to alter some of the default behaviour of the git program. You do that by opening the config file, which you can read with a text editor. Google ‘show hidden files and folders’ for your operating system when that time comes.)</p>
<ol start="2" style="list-style-type: decimal">
<li>Let’s make a new file; we can do this by selecting the kind of file we want from the <code>new</code> dropdown menu. Select ‘text file’. Jupyter will open its text editor and create a new file for you called <code>untitled.txt</code>. Click on the name to change it to <code>exercise1.md</code>. Type in the editor to add some information in it - perhaps a note about what you’re trying to do- then hit save. <strong>Do not hit logout</strong>.</li>
</ol>
<ol style="list-style-type: lower-alpha">
<li>From the Jupyter home screen, hit <code>new</code> and select terminal. At the prompt type <code>$ git status</code></li>
<li>Git will respond with a couple of pieces of information. It will tell you which <code>branch</code> you are on. It will list any untracked files present or new changes that are unstaged. We now will <code>stage</code> those changes to be added to our commit history by typing <code>$ git add -A</code>. (the bit that says <code>-A</code> adds any new, modified, or deleted files to your commit when you make it. There are <a href="https://stackoverflow.com/questions/572549/difference-between-git-add-a-and-git-add#572660">other options or flags</a> where you add <em>only</em> the new and modified files, <em>or</em> only the modified and deleted files.)</li>
<li>Let’s check our git status again: type <code>$ git status</code></li>
<li>You should see something like this:</li>
</ol>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">On</span> branch master
<span class="kw">Initial</span> commit
<span class="kw">Changes</span> to be committed:
<span class="kw">(use</span> <span class="st">"git rm --cached <file>..."</span> to unstage<span class="kw">)</span>
<span class="kw">new</span> file: exercise1.md<span class="kw">```</span></code></pre></div>
<ol start="5" style="list-style-type: lower-alpha">
<li>Let’s take a snapshot: type <code>$ git commit -m "My first commit"</code>. Nothing much seems to have happened; a new <code>$</code> is displayed. In this kind of environment, no news is good news. It’s only often when something goes wrong that you’ll see the terminal print out information. For some users (especially if you are approaching these exercises via DHBox rather than our Binder environment) there could be an error at this point. Git keeps track not only of the changes, but <em>who</em> is making them. Git might ask you for your name and email. Helpfully, the Git error message tells you exactly what to do: type <code>$ git config --global user.email "you\@example.com"</code> and then type <code>$ git config --global user.name "Your Name"</code>. Now try making your first commit.</li>
</ol>
<p>Congratulations, you are now able to track your changes, and keep your materials under version control!</p>
<ol start="3" style="list-style-type: decimal">
<li>Go ahead and make some more changes to your repository. Add some new files. Commit your changes after each new file is created. Now we’re going to view the history of your commits. Type <code>$ git log</code>. What do you notice about this list of changes? Look at the time stamps. You’ll see that the entries are listed in reverse chronological order. Each entry has its own ‘hash’ or unique ID, the person who made the commit and time are listed, as well as the commit message eg:</li>
</ol>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">commit</span> 253506bc23070753c123accbe7c495af0e8b5a43
<span class="kw">Author</span>: Shawn Graham <span class="kw"><</span>shawn.graham@carleton.ca<span class="kw">></span>
<span class="kw">Date</span>: Tue Feb 14 18:42:31 2017 +0000
<span class="kw">Fixed</span> the headings that were broken in the about section of readme.md</code></pre></div>
<ol style="list-style-type: lower-alpha">
<li>We’re going to go back in time and create a new branch. You can escape the <code>git log</code> by typing <code>q</code>. Here’s how the command will look: <code>$ git checkout -b branchname <commit></code> where <code>branch</code> is the name you want the branch to be called, and <code><commit></code> is that unique ID. Make a new branch from your second last commit (don’t use < or >).</li>
<li>We typed <code>git checkout -b experiment 253506bc23070753c123accbe7c495af0e8b5a43</code> (<strong>Don’t</strong> copy <em>our</em> command, because our version includes a reference to a commit that doesn’t exist for you! Select a commit reference from your own commit history, which you can inspect with <code>git log</code>). The response: <code>Switched to a new branch 'experiment'</code> Check git status and then list the contents of your repository. What do you see? You should notice that some of the files you had created before seem to have disappeared - congratulations, you’ve time travelled! Those files are not missing; but they <em>are</em> on a different branch (the master branch) and you can’t harm them now. Add a number of new files, making commits after each one. Check your git status, and check your git log as you go to make sure you’re getting everything. Make sure there are no unstaged changes - everything’s been committed.</li>
</ol>
<ol start="4" style="list-style-type: decimal">
<li>Now let’s assume that your <code>experiment</code> branch was successful - everything you did there you were happy with and you want to integrate all of those changes back into your <code>master</code> branch. We’re going to merge things. To merge, we have to go back to the master branch: <code>$ git checkout master</code>. Good practice is to keep separate branches for all major experiments or directions you go. In case you lose track of the names of the branches you’ve created, this command: <code>git branch -va</code> will list them for you.</li>
</ol>
<ol style="list-style-type: lower-alpha">
<li>Now, we merge with <code>$ git merge experiment</code>. Remember, a merge is a special kind of commit that rolls all previous commits from both branches into one - Git will open your text editor and prompt you to add a message (it will have a default message already there if you want it). Save and exit and ta da! Your changes have been merged together.</li>
</ol>
<ol start="5" style="list-style-type: decimal">
<li>One of the most powerful aspects of using Git is the possibility of using it to manage collaborations. To do this, we have to make a copy of your repository available to others as a <code>remote</code>. There are a variety of places on the web where this can be done; one of the most popular at the moment is <a href="http://github.com">Github</a>. Github allows a user to have an unlimited number of <code>public</code> repositories. Public repositories can be viewed and copied by anyone. <code>Private</code> repositories require a paid account, and access is controlled. If you are working on sensitive materials that can only be shared amongst the collaborators on a project, you should invest in an upgraded account (note that you can also control which files get included in commit; see <a href="https://help.github.com/articles/ignoring-files/">this help file</a>. In essence, you simply list the file names you do not want committed; here’s an <a href="https://gist.github.com/octocat/9257657">example</a>). Let’s assume that your materials are not sensitive.</li>
</ol>
<ol style="list-style-type: lower-alpha">
<li>Now we push your work in the repository onto the version that lives at Github.com:</li>
</ol>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="kw">git</span> push -u origin master</code></pre></div>
<p><em>NB</em> If you wanted to push a <code>branch</code> to your repository on the web instead, do you see how you would do that? If your branch was called <code>experiment</code>, the command would look like this:</p>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">git</span> push origin experiment</code></pre></div>
<ol start="2" style="list-style-type: lower-alpha">
<li>Because your repository is on the web at Github, it is possible that you might make changes to the repository directly there, or from your local machine. To get the updates to integrate into where you are currently working, you could type</li>
</ol>
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="kw">git</span> pull origin master</code></pre></div>
<p>and then begin working.</p>
</div>
<div id="warnings" class="section level3">
<h3><span class="header-section-number">1.3.6</span> Warnings</h3>
<p>This only scratches the surface of what Git and Github can do. Remember that git is the program that keeps snapshots of your work and enables version control. Github is a place that lets you share that sequence of snapshots and files so that others can contribute changes. More information about Git and some exercises conceived for the DHBox/Linux/Mac are available <a href="http://workbook.craftingdigitalhistory.ca/module-1/Exercises/#exercise-4-a-detailed-look-at-using-git-on-the-command-line">here</a>. Although it is possible to make changes to files directly via the edit button on Github, you should be careful if you do this, because things rapidly can become out of sync, resulting in conflicts between differing versions of the same file. <em>Get in the habit of making your changes on your own machine, and making sure things are committed and up-to-date (<code>git status</code>, <code>git pull origin master</code>, <code>git fetch upstream</code> are your friends) before beginning work</em>. At this point, you might want to investigate some of the graphical interfaces for Git (such as <a href="https://desktop.github.com/">Github Desktop</a>). Knowing as you do how things work from the command line, the idiosyncrasies of the graphical interfaces will make more sense. For further practice on the ins-and-outs of Git and Github Desktop, we recommend trying <a href="https://github.com/jlord/git-it-electron/">the Git-it app</a> by Jessica Lord.</p>
<p>For help in resolving merge conflicts, see the <a href="https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/">Github help documentation</a>. For a quick reminder of how the workflow should go, see <a href="https://gist.github.com/shawngraham/513d4b2860d52fdac6bd783e4387957e">this cheat-sheet by Chase Pettit</a>.</p>
</div>
</div>
</section>
</div>
</div>
</div>
<a href="project-management-basics.html" class="navigation navigation-prev " aria-label="Previous page"><i class="fa fa-angle-left"></i></a>
<a href="open-notebook-research-scholarly-communication.html" class="navigation navigation-next " aria-label="Next page"><i class="fa fa-angle-right"></i></a>
</div>
</div>
<script src="libs/gitbook-2.6.7/js/app.min.js"></script>
<script src="libs/gitbook-2.6.7/js/lunr.js"></script>
<script src="libs/gitbook-2.6.7/js/plugin-search.js"></script>
<script src="libs/gitbook-2.6.7/js/plugin-sharing.js"></script>
<script src="libs/gitbook-2.6.7/js/plugin-fontsettings.js"></script>
<script src="libs/gitbook-2.6.7/js/plugin-bookdown.js"></script>
<script src="libs/gitbook-2.6.7/js/jquery.highlight.js"></script>
<script>
gitbook.require(["gitbook"], function(gitbook) {
gitbook.start({
"sharing": {
"github": false,
"facebook": true,
"twitter": true,
"google": false,
"linkedin": false,
"weibo": false,
"instapper": false,
"vk": false,
"all": ["facebook", "google", "twitter", "linkedin", "weibo", "instapaper"]
},
"fontsettings": {
"theme": "white",
"family": "sans",
"size": 2
},
"edit": {
"link": "https://github.com/o-date/draft/edit/gh-pages/01.3-githubandversioncontrol.Rmd",
"text": "Edit"
},
"download": ["odate.pdf"],
"toc": {
"collapse": "section",
"number_sections": null
}
});
});
</script>
</body>
</html>