Everyone should be using a version control system for their work, even if they’re working alone. There are many version control systems out there, but Git is an industry standard and even if one uses another system chances are high one still encounters Git repositories.
Most learners in a CodeRefinery workshop have developed code for a few years. A majority have already encountered Git and have used it to some extent, but in most cases they do not yet feel comfortable with it. They lack a good mental model of how Git operates and are afraid of making mistakes. Other learners have never used Git before. This lesson teaches how things are done in Git, which is useful for the newcomers, but also how Git operates (e.g. what commits and branches really are) and what are some good practices (e.g. how to use the staging area), which is useful for more experienced users.
By the end of this lesson, learners should:
.git/, and have a mental model of how that relates to the working directory
git revertand discard changes using
git checkoutcan be dangerous if changes have not been staged
git checkout, and realize how they’re in fact similar
In a typical workshop the optional in-browser episode is not taught. But if you intend to teach it:
Mirror a fresh https://github.com/coderefinery/example-project from https://github.com/bast/example-project.
Do not just fork it since it can confuse users sending pull requests.
Some participants will be new to using a terminal text editor so please open, edit, and close the editor (Nano) slowly in first type-along sessions and exercises to avoid that participants will fall behind the instructor. At one point a student did not follow the file edits of the instructor, and to correct the mistake they had to do a manual merge, which they were not ready for.
The whole lesson covers why you would use git, how to use it, and practical tips. The earlier lessons are long, the later ones go quite fast.
The “Basics” section is the core of how to use git, and from there sections do just what they say. “Basics”, “Branching and merging”, and “Conflict resolution” are the shortest basics of git (collaboration is another lesson).
“Motivation”, “Basics” and “Sharing repositories online” is the shortest path to a single-user Dropbox-like usage.
If your audience doesn’t need to be taught the “how” and only the “why”, you can present sections “Motivation” and “Tips”, which should explain the high-level picture, and they should use git better, if they already know the basics.
Optional sections: For a complete beginner exposed to version control the half day schedule is too long. These section can be skipped:
“Using the Git staging area” can be skipped but is somewhat useful. It would also make a good homework or advanced assignment.
“Git under the hood” can be skipped if time is tight - it is not important to typical use.
The short section “Sharing repositories online GitHub” is here to give people a very simple taste of remote mirroring, and can be skipped we are exposed to GitHub in another lesson on the same afternoon. Otherwise it can be skipped or moved to another module.
The “In-browser session” can be taught to audiences who need to be able to commit to existing repositories (e.g. documentation, webpages, …) but may not want to use command line.
Most episodes have standard exercises followed by optional (often more advanced) exercises for more experienced learners so they don’t get bored waiting for the newcomers. The instructor should briefly introduce the exercises and mention that after finishing the standard exercise (and indicating that using the green sticky) the learners can move on to the optional ones if they wish. When at least half of the learners have raised the green sticky the instructor should go through the standard exercise to describe its most important take-home messages. It’s also fine to briefly go though important points from the optional exercises, but don’t spend too much time on it since everyone will not have attempted them.
git reset --hard in passing in the
“Clean history” section.
Motivation for this was to allow participants to experiment with the staging and “mess things up” but later be able to continue with branching and see the same things when inspecting git graph. The reset command is there introduced in passing. This can create confusion. But it is also important that participants see the same thing as on the big screen (they often notice the tiniest differences and ask about it).
Some episodes have a “test your understanding” exercise at the end which is intended as formative assessment, i.e. an activity that provides feedback to instructors and learners on whether learning objectives are being met. The instructor should end each episode by posing the “test your understanding” multiple-choice question, giving learners a minute to think about it, and then asking for the right answer or asking learners to raise their hands to signal which answer they think is correct.
We use screenshots from a violent video game in the section on conflict resolution, but it should be emphasized that conflicts are a good thing since otherwise collaborators would overwrite each other’s changes. Git saves us from this situation by producing conflicts.
Key lesson is how to find when something is broken or what commit has broken the code.
It can be useful to emphasize that it
can be really valuable to be able to search through the history of a project
efficiently to find when bugs were introduced or when something changed and
Also show that
git annotate and
git show are available
on GitHub and GitLab.
git annotate and
git bisect the “when” is more important than “who”. It is not
to blame anybody but rather to find out whether published results are affected.
Discuss how one would find out this information without version control.
Questions to involve participants:
git bisect exercise:
Learners may get stuck in the
git bisect exercise if they incorrectly assign a commit
as bad or good.
To leave the bisect mode and return to the commit before
git bisect start was issued,
one can do
$ git bisect reset
and start over if needed.
It is better to demonstrate the commands live and type-along. Ideally connecting to examples discussed earlier.
The screencasting (shell window cheatsheet) hints have been moved to the presenting manual.
Create a “cheatsheet” on the board as you go. After each command is introduced, write it on the board. After each module, make sure you haven’t forgotten anything. Re-create and expand in future git lessons. One strategy is:
commit, etc. See the visual cheat sheet below.
You can get inspired by http://www.ndpsoftware.com/git-cheatsheet.html to make your cheatsheet, but if you show this make it clear there are far, far more commands on there than you need to know right now., and it’s probably too confusing to use after this course. But, the idea of commands moving from the “working dir”, “staging area”, “commits”, etc is good.
We also recommend to draw simple diagrams up on the board (eg: working directory - staging area - repository with commands to move between) and keep them there for students to refer to.
Draw the standard commit graphs on the board early on - you know, the
thing in all the diagrams. Keep it updated all the time. After the
first few samples, you can basically keep using the same graph the
whole lesson. When you are introducing new commands, explain and
update the graph first, then run
git graph, then do the command,
then look at
git graph again.
git diff, and
git graph (our alias) before and
after every command until you get used to things. These give you a clear view
into what is going on, the key to knowing what you are doing. Even
after you are used to things… anytime you do something you do
infrequently, it’s good to check.
git graph is a direct representation of what we are drawing on the
board and should constantly be compared to it.
git add something, it’s almost impossible to lose it.
This is used all the time, for example once you commit or even add
it is hard to lose. Commit before you merge or rebase. And so on.
You probably have a highly optimized bash and git environment - one
that is different from students. Move
of the way before you start so that your environment is identical to
what students have.
The discussion Git vs. Subversion and Git vs. Mercurial in the Motivation section is useful to have in the written material but should be skipped during the lesson unless there are questions.
Typically only very few learners have background in Subversion or Mercurial and the risk is to “waste” 10 minutes on a discussion that nobody can relate to and benefit from.
git restore and
git switch were added in git 2.23 (released
2019-08-16). Sometime much later (2021, 2022, or 2023) perhaps, the
older alternatives can be demoted or removed.