forked from LibraryCarpentry/lc-git
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathinstructor-notes.html
496 lines (460 loc) · 21.8 KB
/
instructor-notes.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
<!DOCTYPE html>
<!-- START: inst/pkgdown/templates/layout.html --><!-- Generated by pkgdown: do not edit by hand --><html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Library Carpentry: Introduction to Git: Instructor Notes</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="assets/styles.css">
<script src="assets/scripts.js" type="text/javascript"></script><!-- mathjax --><script type="text/x-mathjax-config">
MathJax.Hub.Config({
config: ["MMLorHTML.js"],
jax: ["input/TeX","input/MathML","output/HTML-CSS","output/NativeMML", "output/PreviewHTML"],
extensions: ["tex2jax.js","mml2jax.js","MathMenu.js","MathZoom.js", "fast-preview.js", "AssistiveMML.js", "a11y/accessibility-menu.js"],
TeX: {
extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"]
},
tex2jax: {
inlineMath: [['\\(', '\\)']],
displayMath: [ ['$$','$$'], ['\\[', '\\]'] ],
processEscapes: true
}
});
</script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><!-- Responsive Favicon for The Carpentries --><link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="favicon-16x16.png">
<link rel="manifest" href="site.webmanifest">
<link rel="mask-icon" href="safari-pinned-tab.svg" color="#5bbad5">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="theme-color" content="#ffffff">
</head>
<body>
<header id="top" class="navbar navbar-expand-md navbar-light bg-white top-nav library"><a class="visually-hidden-focusable skip-link" href="#main-content">Skip to main content</a>
<div class="container-fluid top-nav-container">
<div class="col-md-6">
<div class="large-logo">
<img alt="Library Carpentry" src="assets/images/library-logo.svg">
</div>
</div>
<div class="selector-container">
<div class="dropdown">
<button class="btn btn-secondary dropdown-toggle bordered-button" type="button" id="dropdownMenu1" data-bs-toggle="dropdown" aria-expanded="false">
<i aria-hidden="true" class="icon" data-feather="eye"></i> Learner View <i data-feather="chevron-down"></i>
</button>
<ul class="dropdown-menu" aria-labelledby="dropdownMenu1">
<li><button class="dropdown-item" type="button" onclick="window.location.href='instructor/instructor-notes.html';">Instructor View</button></li>
</ul>
</div>
</div>
</div>
<hr></header><nav class="navbar navbar-expand-xl navbar-light bg-white bottom-nav library" aria-label="Main Navigation"><div class="container-fluid nav-container">
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
<span class="menu-title">Menu</span>
</button>
<div class="nav-logo">
<img class="small-logo" alt="Library Carpentry" src="assets/images/library-logo-sm.svg">
</div>
<div class="lesson-title-md">
Library Carpentry: Introduction to Git
</div>
<div class="search-icon-sm">
<!-- TODO: do not show until we have search
<i role="img" aria-label="search button" data-feather="search"></i>
-->
</div>
<div class="desktop-nav">
<ul class="navbar-nav me-auto mb-2 mb-lg-0">
<li class="nav-item">
<span class="lesson-title">
Library Carpentry: Introduction to Git
</span>
</li>
<li class="nav-item">
<a class="nav-link" href="key-points.html">Key Points</a>
</li>
<li class="nav-item">
<a class="nav-link" href="reference.html#glossary">Glossary</a>
</li>
<li class="nav-item">
<a class="nav-link" href="profiles.html">Learner Profiles</a>
</li>
<li class="nav-item dropdown">
<button class="nav-link dropdown-toggle" id="navbarDropdown" data-bs-toggle="dropdown" aria-expanded="false">
More <i data-feather="chevron-down"></i>
</button>
<ul class="dropdown-menu" aria-labelledby="navbarDropdown">
<li><a class="dropdown-item" href="discuss.html">Discussion</a></li>
<li><a class="dropdown-item" href="reference.html">FIXME</a></li>
</ul>
</li>
</ul>
</div>
<form class="d-flex col-md-2 search-form">
<fieldset disabled>
<input class="form-control me-2 searchbox" type="search" placeholder="Search" aria-label="Search"><button class="btn btn-outline-success tablet-search-button" type="submit">
<i class="search-icon" data-feather="search" role="img" aria-label="search button"></i>
</button>
</fieldset>
</form>
</div>
<!--/div.container-fluid -->
</nav><div class="col-md-12 mobile-title">
Library Carpentry: Introduction to Git
</div>
<aside class="col-md-12 lesson-progress"><div style="width: %" class="percentage">
%
</div>
<div class="progress library">
<div class="progress-bar library" role="progressbar" style="width: %" aria-valuenow="" aria-label="Lesson Progress" aria-valuemin="0" aria-valuemax="100">
</div>
</div>
</aside><div class="container">
<div class="row">
<!-- START: inst/pkgdown/templates/navbar.html -->
<div id="sidebar-col" class="col-lg-4">
<div id="sidebar" class="sidebar">
<nav aria-labelledby="flush-headingEleven"><button role="button" aria-label="close menu" alt="close menu" aria-expanded="true" aria-controls="sidebar" class="collapse-toggle">
<i class="search-icon" data-feather="x" role="img"></i>
</button>
<div class="sidebar-inner">
<div class="row mobile-row">
<div class="col">
<div class="sidenav-view-selector">
<div class="accordion accordion-flush" id="accordionFlush9">
<div class="accordion-item">
<h2 class="accordion-header" id="flush-headingNine">
<button class="accordion-button collapsed" id="instructor" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseNine" aria-expanded="false" aria-controls="flush-collapseNine">
<i id="eye" aria-hidden="true" class="icon" data-feather="eye"></i> Learner View
</button>
</h2>
<div id="flush-collapseNine" class="accordion-collapse collapse" aria-labelledby="flush-headingNine" data-bs-parent="#accordionFlush2">
<div class="accordion-body">
<a href="instructor/instructor-notes.html">Instructor View</a>
</div>
</div>
</div>
<!--/div.accordion-item-->
</div>
<!--/div.accordion-flush-->
</div>
<!--div.sidenav-view-selector -->
</div>
<!--/div.col -->
<hr>
</div>
<!--/div.mobile-row -->
<div class="accordion accordion-flush" id="accordionFlush11">
<div class="accordion-item">
<button id="chapters" class="accordion-button show" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseEleven" aria-expanded="false" aria-controls="flush-collapseEleven">
<h2 class="accordion-header chapters" id="flush-headingEleven">
EPISODES
</h2>
</button>
<div id="flush-collapseEleven" class="accordion-collapse show collapse" aria-labelledby="flush-headingEleven" data-bs-parent="#accordionFlush11">
<div class="accordion-body">
<div class="accordion accordion-flush" id="accordionFlush1">
<div class="accordion-item">
<div class="accordion-header" id="flush-heading1">
<a href="index.html">Summary and Setup</a>
</div>
<!--/div.accordion-header-->
</div>
<!--/div.accordion-item-->
</div>
<!--/div.accordion-flush-->
<div class="accordion accordion-flush" id="accordionFlush2">
<div class="accordion-item">
<div class="accordion-header" id="flush-heading2">
<a href="01-what-is-git.html">1. What is Git/GitHub?</a>
</div>
<!--/div.accordion-header-->
</div>
<!--/div.accordion-item-->
</div>
<!--/div.accordion-flush-->
<div class="accordion accordion-flush" id="accordionFlush3">
<div class="accordion-item">
<div class="accordion-header" id="flush-heading3">
<a href="02-getting-started.html">2. Getting started with Git</a>
</div>
<!--/div.accordion-header-->
</div>
<!--/div.accordion-item-->
</div>
<!--/div.accordion-flush-->
<div class="accordion accordion-flush" id="accordionFlush4">
<div class="accordion-item">
<div class="accordion-header" id="flush-heading4">
<a href="03-sharing.html">3. Sharing your work</a>
</div>
<!--/div.accordion-header-->
</div>
<!--/div.accordion-item-->
</div>
<!--/div.accordion-flush-->
<div class="accordion accordion-flush" id="accordionFlush5">
<div class="accordion-item">
<div class="accordion-header" id="flush-heading5">
<a href="04-review.html">4. Review</a>
</div>
<!--/div.accordion-header-->
</div>
<!--/div.accordion-item-->
</div>
<!--/div.accordion-flush-->
<div class="accordion accordion-flush" id="accordionFlush6">
<div class="accordion-item">
<div class="accordion-header" id="flush-heading6">
<a href="05-github-pages.html">5. GitHub Pages</a>
</div>
<!--/div.accordion-header-->
</div>
<!--/div.accordion-item-->
</div>
<!--/div.accordion-flush-->
</div>
</div>
</div>
<hr class="half-width">
<div class="accordion accordion-flush resources" id="accordionFlush12">
<div class="accordion-item">
<h2 class="accordion-header" id="flush-headingTwelve">
<button class="accordion-button collapsed" id="resources" type="button" data-bs-toggle="collapse" data-bs-target="#flush-collapseTwelve" aria-expanded="false" aria-controls="flush-collapseTwelve">
RESOURCES
</button>
</h2>
<div id="flush-collapseTwelve" class="accordion-collapse collapse" aria-labelledby="flush-headingTwelve" data-bs-parent="#accordionFlush12">
<div class="accordion-body">
<ul>
<li>
<a href="key-points.html">Key Points</a>
</li>
<li>
<a href="reference.html#glossary">Glossary</a>
</li>
<li>
<a href="profiles.html">Learner Profiles</a>
</li>
<li><a href="discuss.html">Discussion</a></li>
<li><a href="reference.html">FIXME</a></li>
</ul>
</div>
</div>
</div>
</div>
<hr class="half-width resources">
<a href="aio.html">See all in one page</a>
<hr class="d-none d-sm-block d-md-none">
<div class="d-grid gap-1">
</div>
</div>
<!-- /div.accordion -->
</div>
<!-- /div.sidebar-inner -->
</nav>
</div>
<!-- /div.sidebar -->
</div>
<!-- /div.sidebar-col -->
<!-- END: inst/pkgdown/templates/navbar.html-->
<!-- START: inst/pkgdown/templates/content-extra.html -->
<div class="col-xl-8 col-lg-12 primary-content">
<main id="main-content" class="main-content"><div class="container lesson-content">
<h1>Instructor Notes</h1>
<hr>
<div class="section level1">
<h1 id="tips-and-tricks">Tips and Tricks<a class="anchor" aria-label="anchor" href="#tips-and-tricks"></a>
</h1>
<p>Known problems that learners encounter:</p>
<p><em>Windows</em>: When using an outdated version of Windows OpenSSH,
learners cannot set up the SSH connection to GitHub. SOLUTION: Update
OpenSSH version.</p>
<hr>
<div class="section level2">
<h2 id="making-a-handout">Making a handout<a class="anchor" aria-label="anchor" href="#making-a-handout"></a>
</h2>
<p>To make a handout for this lesson, adapt/print from <a href="https://librarycarpentry.org/lc-git/reference.html" class="external-link">https://librarycarpentry.org/lc-git/reference.html</a>.</p>
<hr>
</div>
</div>
<div class="section level1">
<h1 id="general-notes-on-git">General notes on Git<a class="anchor" aria-label="anchor" href="#general-notes-on-git"></a>
</h1>
<p>Using a software tool to handle the versions of your project files
lets you focus on the more interesting/innovative aspects of your
project.</p>
<ul>
<li>Version control’s advantages
<ul>
<li>It’s easy to set up</li>
<li>Every copy of a Git repository is a full backup of a project and its
history</li>
<li>A few easy-to-remember commands are all you need for most day-to-day
version control tasks</li>
<li>The <a href="https://github.com/" class="external-link">GitHub</a> hosting service
provides a web-based collaboration service</li>
</ul>
</li>
<li>Two main concepts
<ul>
<li>
<em>commit</em>: a recorded set of changes in your project’s
files</li>
<li>
<em>repository</em>: the history of all your project’s commits</li>
</ul>
</li>
<li>Why use GitHub?
<ul>
<li>No need for a server: easy to set up</li>
<li>GitHub’s strong community: your colleagues are probably already
there</li>
</ul>
</li>
</ul>
<div class="section level2">
<h2 id="overall">Overall<a class="anchor" aria-label="anchor" href="#overall"></a>
</h2>
<p>Version control might be the most important topic we teach, but Git
is definitely the most complicated tool. However, GitHub presently
dominates the open software repository landscape, so the time and effort
required to teach fundamental Git is justified and worthwhile.</p>
<p>Because of this complexity, we don’t teach novice learners about many
interesting topics, such as branching, hashes, and commit objects.</p>
<p>Instead we try to convince them that version control is useful for
researchers working in teams or not, because it is</p>
<ul>
<li>a better way to “undo” changes,</li>
<li>a better way to collaborate than mailing files back and forth,
and</li>
<li>a better way to share your code and other scientific work with the
world.</li>
</ul>
</div>
<div class="section level2">
<h2 id="teaching-notes">Teaching Notes<a class="anchor" aria-label="anchor" href="#teaching-notes"></a>
</h2>
<ul>
<li><p>Resources for “splitting” your shell so that recent commands
remain in view: <a href="https://github.com/rgaiacs/swc-shell-split-window" class="external-link">https://github.com/rgaiacs/swc-shell-split-window</a>.</p></li>
<li><p>Make sure the network is working <em>before</em> starting this
lesson.</p></li>
<li><p>Drawings are particularly useful in this lesson: if you have a
whiteboard, use it to visualise and describe the <a href="https://guides.github.com/introduction/flow/" class="external-link">GitHub
flow</a>.</p></li>
<li><p>Version control is usually not the first subject in a workshop,
so get learners to create a GitHub account after the session before.
Remind learners that the username and email they use for GitHub (and
setup during Git configuration) will be viewable to the public by
default. However, there are many reasons why a learner may not want
their personal information viewable, and GitHub has <a href="https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address" class="external-link">resources
for keeping an email address private</a>.</p></li>
<li><p>If some learners are using Windows, there will inevitably be
issues merging files with different line endings. (Even if everyone’s on
some flavor of Unix, different editors may or may not add a newline to
the last line of a file.) Take a moment to explain these issues, since
learners will almost certainly trip over them again. If learners are
running into line ending problems, GitHub has a <a href="https://help.github.com/en/articles/dealing-with-line-endings" class="external-link">page</a>
that helps with troubleshooting.</p></li>
<li><p>We don’t use a Git GUI in these notes because we haven’t found
one that installs easily and runs reliably on the three major operating
systems, and because we want learners to understand what commands are
being run. That said, instructors should demo a GUI on their desktop at
some point during this lesson and point learners at <a href="https://git-scm.com/downloads/guis" class="external-link">this page</a>.</p></li>
<li><p>Instructors should show learners graphical diff/merge tools like
<a href="https://sourcegear.com/diffmerge/" class="external-link">DiffMerge</a>.</p></li>
<li><p>When appropriate, explain that we teach Git rather than CVS,
Subversion, or Mercurial primarily because of GitHub’s growing
popularity: CVS and Subversion are now seen as legacy systems, and
Mercurial isn’t nearly as widely used in the sciences right
now.</p></li>
<li>
<p>Further resources:</p>
<ul>
<li>
<a href="https://github.com/jlord/git-it-electron#git-it-desktop-app" class="external-link">git-it</a>
is a self-paced command-line Git demo, with <a href="https://github.com/jlord/git-it-electron" class="external-link">git-it-electron</a> its
GitHub Desktop successor.</li>
<li>Try GitHub’s <a href="https://try.github.io/" class="external-link">resources to learn
Git</a> or Codeacademy’s <a href="https://www.codecademy.com/learn/learn-git" class="external-link">Learn Git</a>.</li>
<li>For instructors, <a href="https://tom.preston-werner.com/2009/05/19/the-git-parable.html" class="external-link">the
Git parable</a> is useful background reading.</li>
</ul>
</li>
</ul>
</div>
</div>
<section id="aggregate-instructor-notes"></section>
</div>
</main>
</div>
<!-- END : inst/pkgdown/templates/content-extra.html -->
</div>
<!--/div.row-->
<footer class="row footer mx-md-3"><hr>
<div class="col-md-6">
<p>This lesson is subject to the <a href="CODE_OF_CONDUCT.html">Code of Conduct</a></p>
<p>
<a href="https://github.com/librarycarpentry/lc-git/edit/main/README.md" class="external-link">Edit on GitHub</a>
| <a href="https://github.com/librarycarpentry/lc-git/blob/main/CONTRIBUTING.md" class="external-link">Contributing</a>
| <a href="https://github.com/librarycarpentry/lc-git/" class="external-link">Source</a></p>
<p><a href="https://github.com/librarycarpentry/lc-git/blob/main/CITATION" class="external-link">Cite</a> | <a href="mailto:[email protected]">Contact</a> | <a href="https://carpentries.org/about/" class="external-link">About</a></p>
</div>
<div class="col-md-6">
<p>Materials licensed under <a href="LICENSE.html">CC-BY 4.0</a> by the authors</p>
<p><a href="https://creativecommons.org/licenses/by-sa/4.0/" class="external-link">Template licensed under CC-BY 4.0</a> by <a href="https://carpentries.org" class="external-link">The Carpentries</a></p>
<p>Built with <a href="https://github.com/carpentries/sandpaper/tree/0.13.0" class="external-link">sandpaper (0.13.0)</a>,
<a href="https://github.com/carpentries/pegboard/tree/0.6.1" class="external-link">pegboard (0.6.1)</a>,
and <a href="https://github.com/carpentries/varnish/tree/0.3.0" class="external-link">varnish (0.3.0)</a>.</p>
</div>
</footer>
</div> <!-- / div.container -->
<div id="to-top">
<a href="#top">
<i class="search-icon" data-feather="arrow-up" role="img" aria-label="Back to top"></i><br><span class="d-none d-sm-none d-md-none d-lg-none d-xl-block">Back</span> To Top
</a>
</div>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TrainingMaterial",
"@id": "https://librarycarpentry.github.io/lc-git/instructor-notes.html",
"dct:conformsTo": "https://bioschemas.org/profiles/TrainingMaterial/1.0-RELEASE",
"description": "A Carpentries Lesson teaching foundational data and coding skills to researchers worldwide",
"keywords": "software, data, lesson, The Carpentries",
"name": "Instructor Notes",
"creativeWorkStatus": "active",
"url": "https://librarycarpentry.github.io/lc-git/instructor-notes.html",
"identifier": "https://librarycarpentry.github.io/lc-git/instructor-notes.html",
"dateCreated": "2018-04-12",
"dateModified": "2023-09-19",
"datePublished": "2023-09-19"
}
</script><script>
feather.replace();
</script><!-- Matomo
2022-11-07: we have gotten a notification that we have an overage for our
tracking and I'm pretty sure this has to do with Workbench usage.
Considering that I am not _currently_ using this tracking because I do not
yet know how to access the data, I am turning this off for now.
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(["setDocumentTitle", document.domain + "/" + document.title]);
_paq.push(["setDomains", ["*.preview.carpentries.org","*.datacarpentry.github.io","*.datacarpentry.org","*.librarycarpentry.github.io","*.librarycarpentry.org","*.swcarpentry.github.io", "*.carpentries.github.io"]]);
_paq.push(["setDoNotTrack", true]);
_paq.push(["disableCookies"]);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="https://carpentries.matomo.cloud/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '1']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src='https://cdn.matomo.cloud/carpentries.matomo.cloud/matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
End Matomo Code -->
</body>
</html><!-- END: inst/pkgdown/templates/layout.html-->