How to teach Git to beginners in a workshop

Git has dozens of commands, and a beginner needs about five to do something useful by the end of the first hour. The Software Carpentry instructor notes for their Git lesson put it bluntly: version control may be the most important topic they teach, but Git is the most complicated tool, so teach only the fundamentals and skip branching, hashes and commit objects with novices.

A first workshop that works covers one loop and repeats it:

• git init once, to start tracking a folder.
• git status constantly, to see what Git sees.
• git add to choose what goes into the next save.
• git commit -m "…" to save it.
• git log --oneline to see the saves so far.

Once that loop feels routine, add git diff to see what changed, and, if you have the time and everyone has an account, git push to a hosting service. Each new command is a new step, never two in one.

Start with five minutes on why anyone bothers. The same instructor notes suggest a short overview of what version control does for learners before the hands-on part: going back to yesterday's version, seeing who changed what, working on one project with other people. Beginners who know what problem Git solves put up with its vocabulary.

Git's hardest idea for a beginner is the staging area: a change can be saved in the file, added to the next commit, or committed, and those are three different places. Pro Git calls them the working tree, the staging area and the Git directory, and a file moves between them with add and commit.

Draw it before anyone types, and keep the drawing on the board all day. Three boxes side by side, labelled "your folder", "next commit" and "history", with an arrow for each command. When a student asks why their commit is empty, point at the drawing: the change is still in the first box. The Carpentries' notes recommend drawings throughout this lesson, and a diagram of the separate repositories once a remote appears, since beginners easily mix up Git and the website that hosts it.

Their Git lesson has a good picture for the staging area too. git add chooses who is in the photo, and git commit takes it. Skipping the choice, with git commit -a, is like calling everyone in for a group photo: someone ends up in it by accident.

Every Git command changes something students can't see. git status makes it visible, and it says in plain words what to do next. Have students run it after every command for the whole first workshop, and say out loud what you expect it to print before you run it yourself.

That gives every step a result students can check without you:

• After git init: "No commits yet".
• After saving a new file: "Untracked files", with the file's name in red.
• After git add: "Changes to be committed", the name in green.
• After git commit: "nothing to commit, working tree clean".

Put the expected output in the step itself, so a student can compare. If what they see doesn't match, they know before the class moves on, not twenty minutes later when a push fails. The same notes call git status the tool for diagnosing problems, such as a conflict resolved in the file but never added.

Git workshops go wrong in the same places, so write the fix into the step before the class meets it. The Carpentries' instructor notes list the common ones:

• Running commands in the wrong folder. "fatal: not a git repository" means the student is outside the project. Show pwd early.
• The editor that opens by itself. git commit without -m drops beginners into an editor they can't leave. Teach -m from the start, or set an editor everyone knows during setup; the Carpentries use nano because it shows its own shortcuts.
• Someone else's name on their commits. Students copy your git config line with your name and email in it. Make "check your name with git config --list" part of setup.
• A mistyped remote. The address pasted wrong means push fails; git remote -v shows what Git has.
• Pushing before pulling once two people share a repository.

Do the installing before the day, from a setup page that ends in a check people run themselves (getting everyone set up in the first five minutes covers it). A Git workshop that starts with installs eats its own first hour.

Practice should feel like a real project, but a tiny one: a folder with one text file, where each step changes a line and saves a commit. A step reads like "Add a line about Mars to planets.txt, add it, commit it with the message Add Mars, then run git log --oneline. You're done when you see two commits." The student checks the last sentence by looking at their screen.

Keep commit messages short and about what changed. The Software Carpentry lesson suggests starting each message with a summary under 50 characters, and the PLOS paper "Ten Simple Rules for Taking Advantage of Git and GitHub" repeats the old advice: commit early, commit often. Small commits also make the history readable in git log --oneline, which makes the next step, going back to an earlier version, easier to teach.

Save conflicts for the end, and save time for them. The instructor notes warn that conflicts come late in the lesson, when everyone is tired, and that both learners and instructor make more mistakes then. Plan a break right after.

In Workshopy a workshop is a list of steps that students follow on their own screens while you watch the room. Write each Git step with its commands in a code block (students copy them with one press instead of reading them off a projector), then end it with a Check your work block: students paste what git status or git log --oneline printed and press Check. The server compares the paste with what you wrote, so the answer never reaches their screen.

```check
Paste what `git status` printed.

contains: nothing to commit, working tree clean

mistake: Changes to be committed → You staged the file but didn't commit it.
mistake: not a git repository → You're outside the project folder. Run `cd planets`.
hint: Run all three lines, in order, from inside `planets`.
```

A paste that holds one of the mistakes you foresaw gets your words for it, and each wrong try opens the next hint. A right paste marks the step done. On your screen, beside the step, you see how many students passed and every wrong paste grouped, with "you foresaw it" on the ones you wrote a mistake for. The room marks who pressed Done without checking. A paste nobody foresaw is often a new Git error worth explaining to the whole room.

A teacher block in the step holds your own notes, such as the folder slip and the missing -m; students never get it. A student who is stuck presses Need help and can say what Git printed; the Help tab lists the requests oldest first. If a step has a mistake in it, edit it during the class and every student's screen updates. After the class, the report shows each step's checks: who passed, who didn't check, and the wrong pastes the class gave most, which tells you which Git step to rewrite before next time.