flowchart TD
classDef layer fill:#f7f9fc,stroke:#c7d2e0,color:#1f2933;
A0["<b>Arrival</b> setup check, no teaching"]:::layer
A["<b>Part 1</b> Welcome, concept-map baseline"]:::layer
B["<b>Part 2</b> Create and clone"]:::layer
C["<b>Part 3</b> The commit cycle"]:::layer
D["<b>Part 4</b> Team work (the push wall)"]:::layer
LU["<b>Lunch</b>"]:::layer
E["<b>Part 5</b> Work on a branch"]:::layer
F["<b>Part 6</b> Pull request, review, merge"]:::layer
G["<b>Part 7</b> Merge conflict (demo)"]:::layer
H["<b>Part 8</b> Concept-map revisit and wrap-up"]:::layer
A0 --> A --> B --> C --> D --> LU --> E --> F --> G --> H
11 Run of show
This chapter is the run of show: the session, block by block. The first part is the general structure that every iteration of the course shares, written as a reusable template. The second part is a worked example, the gitforsci-ghe iteration, the most recent full four-hour run and the reference this handbook is now built from.
Each block follows the same rhythm: motivate it, demonstrate it once (“my turn”), hand it over as a “your turn” task, then regroup. Some steps the whole room does together (“our turn”). The concept drawings (Chapter 4) are cued where they fit, always as the end-of-block summary, and concept maps bookend the day (Section 4.5).
11.1 The general structure
The gitforsci-ghe run settled the course into an eight-part arc, and that is the structure to teach from. The timings below are a starting point for a session that runs from arrival to wrap-up across roughly five clock hours (about four hours of teaching) with a lunch and short breaks. Adjust to your room, but keep the proportion: most of the time is learners’ hands on keyboards, not slides. The collaboration center is deliberately built up in four steps (commit cycle, a team-work “push wall” that fails on purpose, branching, then the pull request) rather than one, so the pull request lands on top of a motivation the learners felt themselves.
Important
Protect the ending, not the middle. Two blocks are non-negotiable: Part 6 (pull request, review, merge) is the centerpiece, and Part 8 (the concept-map revisit and wrap-up) is what makes the day’s learning visible. If you are running behind, cut Part 7 (the merge-conflict demo) first; it is instructor-only and the least costly to drop. Never sacrifice Part 6 or Part 8 to save Part 7.
11.2 Room mechanics that run all day
Four small mechanics from the gitforsci-ghe run carry every block; set them up once and they pace the whole day.
- The sticky-note done-signal. A yellow sticky note waits on every seat. A learner who finishes a “your turn” task puts the sticky note on their laptop; you read the room at a glance instead of asking for hands. Remote participants type “done” (or “blocked”) in the video-call chat instead.
- The bounded regroup. After each “your turn”: two minutes of regroup, then park-and-pair. Anyone still stuck is paired with a finished neighbor or parked for a 1:1 fix at the next break. Never let one stuck learner stop the room.
- The pairing record. In Part 4, partners write each other’s GitHub username on their sticky notes. That sticky note is the pairing record, and it returns in Part 6 as the reviewer assignment.
- The location icons. Every “your turn” slide carries two icons that say where a step happens: one for RStudio on the learner’s machine, one for github.com in the browser. Losing track of which surface they are on is one of the most common beginner confusions, and the icons quietly remove it.
11.3 Arrival: setup check, no teaching
Goal: everyone arrives with a working setup, so no teaching time is lost to installs.
- As learners arrive, confirm RStudio opens, GitHub login works, and the personal access token is set (Chapter 10).
- A helper, not the instructor, handles anyone with a broken setup. If the dry-run showed many unverified pushes, turn this slot into a setup clinic.
No teaching yet. This block exists so Part 1 can start on time with a level room.
11.4 Part 1: Welcome and the baseline concept map
Goal: set the tone and the why, then take a baseline measurement before any mechanics.
- Welcome, who you are, and the safe-to-fail promise (Chapter 2).
- Say the two anchor lines early: this is not an AI workshop today (that is the follow-up), and it is safe to fail here because almost everything is reversible.
- Read the room’s own pre-course survey back to them, and name the focus learner you teach to (Appendix C). In the reference run this is Arti, the fearful outsider; teaching to Arti also serves the quicker learners, who get the command behind each click as their stretch material.
- Name the three learning objectives, keyword-led: commit cycle, collaboration, concept map.
Concept-map baseline (bookend 1): introduce concept maps with an everyday exemplar (Section 4.5), then give one prompt: draw how a document currently travels between you and a co-author. Learners pin this baseline map on the wall; it returns in Part 8. Do not correct anything.
11.5 Part 2: Create and clone
Concept: there are two copies of the work, local and remote, and Git moves changes between them.
Drawing: Drawing 1, local and remote (Section 4.1), revealed stage by stage as the summary after the hands-on step.
My turn: create a repository on GitHub (with a README so the clone is never empty), clone it into RStudio, and inspect the local files.
Your turn:
Regroup: confirm everyone has cloned before moving on. This is the foundational loop; do not advance until it works for everyone.
11.6 Part 3: The commit cycle
Concept: every button in RStudio is a Git command underneath; a commit is a labeled snapshot, not a save.
Drawing: Drawing 2, the commit cycle (Section 4.2), as the summary.
My turn: run the mantra out loud in order, Pull, Stage, Commit, Push, and watch the change appear on GitHub. Then two moments the -ghe run proved worth keeping:
- A revert demo (instructor only): make a deliberately bad commit, then revert it from the history, so learners see that Git keeps both the mistake and the undo. Say it plainly: almost everything in Git is reversible.
- A credentials moment: fix everyone’s stored credentials now (for example with
gitcreds::gitcreds_set()and the pre-work token), because the afternoon depends on pushing.
Your turn: the full pull, stage, commit, push cycle on their own file, verified on GitHub. An “our turn” step then starts a commit on GitHub and pulls it down, closing the loop both ways.
Regroup: target every learner with at least two pushed commits before the break.
11.7 Part 4: Team work: the push wall
Concept: you can read a collaborator’s repository but not write to it, and that wall is the reason branches and pull requests exist.
There is no “my turn” here; this block is a collaboration cliffhanger, by design.
Your turn (in pairs):
Debrief and cliffhanger: name what happened (read but not write) in two sentences, and promise that the afternoon solves it properly with branches and pull requests. Do not resolve it now.
The bridge exercise: close the morning with the “match the Git command to the button” handout (from the exercises repository in the development org): draw a line from each Git command to the button that runs it, three minutes alone, then five comparing with the partner. It makes the “a button is a command” idea concrete, and it can spill into lunch without harm, so it doubles as the flexible buffer at the morning’s end.
Then the lunch break. A four-hour day needs a real one; use it to help anyone parked from the morning.
11.8 Part 5: Work on a branch
Concept: a branch is a parallel line of work that splits off and later rejoins, which is what makes collaboration safe.
Drawing: Drawing 3, branching (Section 4.3), with the merge point left empty for Part 6.
My turn: on a shared team repository, create a dev branch, make an edit, and show that the change lives only on dev until it is merged.
Your turn (one driver per team):
Regroup: confirm every team has a branch pushed. This branch feeds the pull request in the next block, so keep momentum.
11.9 Part 6: Pull request, review, merge
This is the centerpiece of the workshop. Give it the most time and care, and never cut it.
Concept: a pull request is a request to merge one branch into another, reviewed by a human before it happens.
Drawing: Drawing 4, the pull request (Section 4.4), completing the merge point from Drawing 3 and showing the review step.
My turn: open a pull request from dev, request a reviewer, leave line comments as the reviewer, then open an issue with a task list next to the pull request, merge, and tick the task off in the issue; back in RStudio, switch to main and pull. The issue moment matters: it plants the wrap-up message that the issue tracker is a task list attached to the work. Say the habit out loud: merged, then pull main and switch back to dev.
Your turn (two roles, then swap):
Regroup: this is where collaboration clicks. Make sure every learner has opened, reviewed, and merged a pull request and pulled the result. If you are behind, Part 7 dies, not this block.
11.10 Part 7: Merge conflict (instructor demo, first to cut)
Concept: a conflict is Git protecting your work, not breaking it; it hands you both edits and waits for you to choose.
My turn (demo only): set up a clash on purpose, pull, walk the conflict markers out loud, resolve, and push. There is no learner exercise here.
If you are behind when you reach this block, skip the demo with one sentence (a conflict is Git refusing to guess; you choose, nothing is lost) and hand the time to Part 8.
11.11 Part 8: Concept-map revisit and wrap-up
Goal: make the day’s learning visible, then point forward. This block has a hard start and is protected.
Concept-map revisit (bookend 2): learners draw a second concept map of Git and GitHub using the day’s vocabulary (repository, clone, commit, push, pull, branch, pull request, merge, review), pin it beside the morning baseline, and walk a partner through what changed (Section 4.5). The comparison is the point.
Ask consent on the slide to photograph the map pairs, anonymously, for the retrospective; send the written consent request by email ahead of the day, so the on-slide ask is a reminder rather than the first time learners hear it.
Wrap-up:
- Recap what they can now do, mapped to the three objectives: commit cycle, collaboration, concept map.
- Name why it matters: issues, commit messages, and reviews are visible to other people and show how you work, a signal that grows as more content is AI-generated.
- Name the side benefits explicitly (Chapter 3): more comfort with R and RStudio, a first taste of Quarto, and reversibility as a habit.
- Point forward to the planned second part on task and project management, and to agentic coding on the longer horizon (see what is still to come).
- Collect feedback while the closing slide is up.
End on momentum: they should leave wanting to use it tomorrow.
After the room empties: photograph the consenting learners’ map pairs, collect the parked-problem list from the helper and answer the open questions the same week, and note the actual per-block times on the iteration’s lesson plan for the retrospective. This half hour is what turns one run into a better next run.
11.12 What makes a good lesson plan
The structure above is the skeleton. A lesson plan is what you flesh it out into for a specific iteration, and a good one earns its place by holding the things the general structure deliberately leaves out:
- Real timings per step, not per block. “Create and clone, 45 minutes” is a block; “create the repo (1), clone in RStudio (3), first commit cycle (5)” is a plan you can actually pace against in the room.
- The exact demonstration script. What you click, in order, and the one or two sentences you say at each click. This is what lets a second instructor teach it the way it was designed.
- The concrete artifacts. The actual repository names, the example usernames, the specific files learners edit. Generic instructions become specific tasks.
- Teaching cues. The questions you ask (“what is origin in Git language?”), the hands-up checks, the points where you expect learners to stall.
- What you are deliberately not doing. Naming the things you skip (forking, conflict resolution, the terminal) keeps the plan honest about its scope.
Most of this does not belong in the general structure, because it is specific to one run. It belongs in the iteration’s own lesson plan, which is why the course keeps one per iteration rather than trying to make a single plan serve every cohort.
11.13 The worked artifact: a real manuscript repository
The collaboration blocks (Parts 5 and 6) work best on a small, real research artifact rather than a toy repository. The gitforsci-ghe run used washinvestments, a short Quarto manuscript built from an open dataset on WASH investment trends, with per-team copies (washinvestments-<team>) so each team collaborates on its own. Learners create a dev branch, edit the manuscript’s author details, render it, and take it through the pull-request cycle. Using a manuscript, not a placeholder, means learners see reproducible research in action and the pull request reviews content that looks like their own work. Pick an artifact from your own domain if you have one; the shape (a renderable document, a couple of editable author or content fields, one clean main) is what matters.
11.14 Worked example: the gitforsci-ghe iteration
The gitforsci-ghe iteration is the reference full-length run: the eight-part arc above, taught entirely in the point-and-click interface of RStudio and GitHub with no terminal work. The full step-by-step plan, with per-step timings and the demonstration script for each “my turn” block, lives alongside the iteration material in gitforsci-ghe/website/workshop/lesson-plan.md; this is the shape of it.
| Block | Time | What happens |
|---|---|---|
| Arrival | 30 min | Setup check as learners arrive; helper handles broken setups. No teaching. |
| Part 1: Welcome, baseline map | 30 min | Motivation, the safe-to-fail and “not an AI workshop” framing, the three objectives, and the baseline concept map (Section 4.5). |
| Part 2: Create and clone | 20 min | Create a website repo with a README, clone into RStudio, inspect the local files. Drawing 1. |
| Break | 10 min | 1:1 fixes for parked learners; the helper takes the list. |
| Part 3: The commit cycle | 30 min | The pull, stage, commit, push mantra; the revert demo; the credentials moment; an “our turn” commit started on GitHub. Drawing 2. |
| Part 4: Team work (push wall) | 20 min | Pair up, clone the partner’s repo, try to push, hit the 403. The collaboration cliffhanger, then the match-the-command handout flexing into lunch. |
| Lunch | 55 min | Hard return time; help parked learners. |
| Part 5: Work on a branch | 20 min | On the team washinvestments repo, create a dev branch, edit author details, render, commit, push. Drawing 3. |
| Part 6: Pull request, review, merge | 40 min | Open a PR, review with line comments, merge, pull main; author and reviewer roles, then swap; the demo adds an issue with a task list. Drawing 4. Protected. |
| Movement break | 5 min | Get up and move. |
| Part 7: Merge conflict | 10 min | Instructor demo only: set up a clash, resolve the markers, push. First to cut. |
| Part 8: Concept-map revisit, wrap-up | 30 min | The second concept map beside the baseline, the wrap-up, and feedback. Protected, hard start. |
Compared with the general structure, this run confirms the settled shape: no terminal work, the collaboration center built up over Parts 3 to 6, and concept maps as the measurement bookends.
11.14.1 An earlier, shorter run: gitforsci-cis
For contrast, the earlier gitforsci-cis iteration compressed the same skeleton into about two hours of teaching split into two modules around one break. It folded the commit cycle into the first module, kept the push-wall motivation, ran a single branch-and-pull-request block, and closed with a short publish step. It is a useful illustration of how the structure compresses for a shorter slot, but the gitforsci-ghe plan above is the current reference.