forked from swcarpentry/git-novice
-
Notifications
You must be signed in to change notification settings - Fork 0
/
instructors.html
168 lines (168 loc) · 15.4 KB
/
instructors.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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<title>Software Carpentry: Version Control with Git</title>
<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap.css" />
<link rel="stylesheet" type="text/css" href="css/bootstrap/bootstrap-theme.css" />
<link rel="stylesheet" type="text/css" href="css/swc.css" />
<link rel="alternate" type="application/rss+xml" title="Software Carpentry Blog" href="http://software-carpentry.org/feed.xml"/>
<meta charset="UTF-8" />
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body class="lesson">
<div class="container card">
<div class="banner">
<a href="http://software-carpentry.org" title="Software Carpentry">
<img alt="Software Carpentry banner" src="img/software-carpentry-banner.png" />
</a>
</div>
<article>
<div class="row">
<div class="col-md-10 col-md-offset-1">
<a href="index.html"><h1 class="title">Version Control with Git</h1></a>
<h2 class="subtitle">Instructor’s Guide</h2>
<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/">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 file</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>
<h2 id="overall">Overall</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>
<h2 id="teaching-notes">Teaching Notes</h2>
<ul>
<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, <a href="https://twitter.com/chendaniely/status/583689081151979520">use it!</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.</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/articles/dealing-with-line-endings/#platform-all">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="http://git-scm.com/downloads/guis">this page</a>.</p></li>
<li><p>Instructors should show learners graphical diff/merge tools like <a href="https://sourcegear.com/diffmerge/">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>
</ul>
<h2 id="automated-version-control"><a href="01-basics.html">Automated Version Control</a></h2>
<ul>
<li><p>Ask, “Who uses ‘undo’ in their editor?” All say “Me”. ‘Undo’ is the simplest form of version control.</p></li>
<li><p>Give learners a five-minute overview of what version control does for them before diving into the watch-and-do practicals. Most of them will have tried to co-author papers by emailing files back and forth, or will have biked into the office only to realize that the USB key with last night’s work is still on the kitchen table. Instructors can also make jokes about directories with names like “final version”, “final version revised”, “final version with reviewer three’s corrections”, “really final version”, and, “come on this really has to be the last version” to motivate version control as a better way to collaborate and as a better way to back work up.</p></li>
</ul>
<h2 id="setting-up-git"><a href="02-setup.html">Setting Up Git</a></h2>
<ul>
<li><p>We suggest instructors and students use <code>nano</code> as the text editor for this lessons because</p>
<ul>
<li>it runs in all three major operating systems,</li>
<li>it runs inside the shell (switching windows can be confusing to students), and</li>
<li>it has shortcut help at the bottom of the window.</li>
</ul>
<p>Please point out to students during setup that they can and should use another text editor if they’re already familiar with it.</p></li>
<li><p>When setting up Git, be very clear what learners have to enter: it is common for them to edit the instructor’s details (e.g. email). Check at the end using <code>git config --list</code>.</p></li>
</ul>
<h2 id="creating-a-repository"><a href="03-create.html">Creating a Repository</a></h2>
<ul>
<li><p>When you do <code>git status</code>, Mac users may see a <code>.DS_Store</code> file showing as untracked. This a file that Mac OS creates in each directory.</p></li>
<li><p>The challenge “Places to create repositories” tries to reinforce the idea that the <code>.git</code> folder contains the whole Git repo and deleting this folder undoes a <code>git init</code>. It also gives the learner the way to fix the common mistake of putting unwanted folders (like <code>Desktop</code>) under version control.</p>
<p>Instead of removing the <code>.git</code> folder directly, you can choose to move it first to a safer directory and remove it from there:</p>
<pre class="input"><code>$ mv .git temp_git
$ rm -rf temp_git </code></pre></li>
</ul>
<h2 id="tracking-changes"><a href="04-changes.html">Tracking Changes</a></h2>
<ul>
<li><p>It’s important that learners do a full commit cycle by themselves (make changes, <code>git add</code>, <code>git diff</code>, and <code>git commit</code>). The “<code>bio</code> repository” challenge does that.</p></li>
<li><p>This is a good moment to show a diff with a graphical diff tool. If you skip it because you’re short on time, show it once in GitHub.</p></li>
</ul>
<h2 id="exploring-history"><a href="05-history.html">Exploring History</a></h2>
<ul>
<li><p>One thing may cause confusion is recovering old versions. If, instead of doing <code>$ git checkout f22b25e mars.txt</code>, someone does <code>$ git checkout f22b25e</code>, they wind up in the “detached HEAD” state and confusion abounds. It’s then possible to keep on committing, but things like <code>git push origin master</code> a bit later will not give easily comprehensible results. It also makes it look like commits can be lost. To “fix” a “detached HEAD”, simply <code>git checkout master</code>.</p></li>
<li><p>This is a good moment to show a log within a Git GUI. If you skip it because you’re short on time, show it once in GitHub.</p></li>
</ul>
<h2 id="ignoring-things"><a href="06-ignore.html">Ignoring Things</a></h2>
<p>Just remember that you can use wildcards and regular expressions to ignore a particular set of files in <code>.gitignore</code>.</p>
<h2 id="remotes-in-github"><a href="07-github.html">Remotes in GitHub</a></h2>
<ul>
<li><p>Make it clear that Git and GitHub are not the same thing: Git is an open source version control tool, GitHub is a company that hosts Git repositories in the web and provides a web interface to interact with repos the host.</p></li>
<li><p>If your learners are advanced enough to be comfortable with SSH, tell them they can use keys to authenticate on GitHub instead of passwords, but don’t try to set this up during class: it takes too long, and is a distraction from the core ideas of the lesson.</p></li>
<li><p>It is very useful to draw a diagram showing the different repositories involved.</p></li>
</ul>
<h2 id="collaborating"><a href="08-collab.html">Collaborating</a></h2>
<ul>
<li><p>Decide in advance whether all the learners will work in one shared repository, or whether they will work in pairs (or other small groups) in separate repositories. The former is easier to set up; the latter runs more smoothly.</p></li>
<li><p>Role playing between two instructors can be effective when teaching the collaboration and conflict sections of the lesson. One instructor can play the role of the repository owner, while the second instructor can play the role of the collaborator. If it is possible, try to use two projectors so that the computer screens of both instructors can be seen. This makes for a very clear illustration to the students as to who does what.</p></li>
<li><p>It is also effective to pair up students during this lesson and assign one member of the pair to take the role of the owner and the other the role of the collaborator. In this setup, challenges can include asking the collaborator to make a change, commit it, and push the change to the remote repository so that the owner can then retrieve it, and vice-versa. The role playing between the instructors can get a bit “dramatic” in the conflicts part of the lesson if the instructors want to inject some humor into the room.</p></li>
<li><p>If you don’t have two projectors, have two instructors at the front of the room. Each instructor does their piece of the collaboration demonstration on their own computer and then passes the projector cord back and forth with the other instructor when it’s time for them to do the other part of the collaborative workflow. It takes less than 10 seconds for each switchover, so it doesn’t interrupt the flow of the lesson. And of course it helps to give each of the instructors a different-colored hat, or put different-colored sticky notes on their foreheads.</p></li>
<li><p>If you’re the only instructor, the best way to create is clone the two repos in your Desktop, but under different names, e.g., pretend one is your computer at work:</p>
<pre class="input"><code>$ git clone https://github.com/vlad/planets.git planets-at-work</code></pre></li>
<li>It’s very common that learners mistype the remote alias or the remote URL when adding a remote, so they cannot <code>push</code>. You can diagnose this with <code>git remote -v</code> and checking carefully for typos.
<ul>
<li>To fix a wrong alias, you can do <code>git remote rename <old> <new></code>.</li>
<li>To fix a wrong URL, you can do <code>git remote set-url <alias> <newurl></code>.</li>
</ul></li>
<li><p>Before cloning the repo, be sure that nobody is inside another repo. The best way to achieve this is moving to the <code>Desktop</code> before cloning: <code>cd && cd Desktop</code>.</p></li>
<li><p>If both repos are in the <code>Desktop</code>, have them to clone their collaborator repo under a given directory using a second argument:</p>
<pre class="input"><code>$ git clone https://github.com/vlad/planets.git vlad-planet`</code></pre></li>
<li><p>The most common mistake is that learners <code>push</code> before <code>pull</code>ing. If they <code>pull</code> afterward, they may get a conflict.</p></li>
<li><p>Conflicts, sometimes weird, will start to arise. Stay tight: conflicts are next.</p></li>
</ul>
<h2 id="conflicts"><a href="09-conflict.html">Conflicts</a></h2>
<ul>
<li><p>Expect the learners to make mistakes. Expect <em>yourself</em> to make mistakes. This happens because it is late in the lesson and everyone is tired.</p></li>
<li><p>If you’re the only instructor, the best way to create a conflict is:</p>
<ul>
<li>Clone your repo in a different directory, pretending is your computer at work: <code>git clone https://github.com/vlad/planets.git planets-at-work</code>.</li>
<li>At the office, you make a change, commit and push.<br /></li>
<li>At your laptop repo, you (forget to pull and) make a change, commit and try to push.</li>
<li><code>git pull</code> now and show the conflict.</li>
</ul></li>
<li><p>Learners usually forget to <code>git add</code> the file after fixing the conflict and just (try to) commit. You can diagnose this with <code>git status</code>.</p></li>
<li><p>Remember that you can discard one of the two parents of the merge:</p>
<ul>
<li>discard the remote file, <code>git checkout --ours conflicted_file.txt</code></li>
<li>discard the local file, <code>git checkout --theirs conflicted_file.txt</code></li>
</ul>
<p>You still have to <code>git add</code> and <code>git commit</code> after this. This is particularly useful when working with binary files.</p></li>
</ul>
<h2 id="open-science"><a href="10-open.html">Open Science</a></h2>
<h2 id="licensing"><a href="11-licensing.html">Licensing</a></h2>
<p>We teach about licensing because questions about who owns what, or can use what, arise naturally once we start talking about using public services like GitHub to store files. Also, the discussion gives learners a chance to catch their breath after what is often a frustrating couple of hours.</p>
<h2 id="hosting"><a href="12-hosting.html">Hosting</a></h2>
<p>A common concern for learners is having their work publicly available on GitHub. While we encourage open science, sometimes private repos are the only choice. It’s always interesting to mention the options to have web-hosted private repositories.</p>
</div>
</div>
</article>
<div class="footer">
<a class="label swc-blue-bg" href="http://software-carpentry.org">Software Carpentry</a>
<a class="label swc-blue-bg" href="https://github.com/swcarpentry/git-novice">Source</a>
<a class="label swc-blue-bg" href="mailto:admin@software-carpentry.org">Contact</a>
<a class="label swc-blue-bg" href="LICENSE.html">License</a>
</div>
</div>
<!-- Javascript placed at the end of the document so the pages load faster -->
<script src="http://software-carpentry.org/v5/js/jquery-1.9.1.min.js"></script>
<script src="css/bootstrap/bootstrap-js/bootstrap.js"></script>
</body>
</html>