A 2-hour hands-on workshop for university teachers
One practical note before you start: the AI assistant understands English — and most other languages — so talk to it in whatever language you think in; the example sentences below are a starting point, not a script you have to copy word for word.
Start from scratch and run through the full everyday cycle twice.
Two people share one mock-paper repo and swap roles, once each.
The AI does: turn plain language into actions, lay out a plan first, run Git, report the state, and draft the commit and PR messages.
You do: confirm which folder you are in and how public it is, read the diff, judge the research content, and decide on restore, revert, merge and deletion.
Rule of thumb: the AI proposes and operates; you understand, verify and decide.
Your folder is full of paper_v2_final_really.docx and final_v3_this_time_really_final.docx. Which one runs — and which one you submitted — is now a question for archaeology; and “last month's version was actually better” cannot be found again.
Co-authors mail attachments back and forth. Two people edit the same version at the same time, nobody can say whose paragraph got overwritten, and “what did you change?” has to be checked by reading line by line.
Journals such as those of the AEA already treat a reproducible data and code bundle (replication package) as a condition of submission. You have to be able to point back at “the complete state of the project on the day I submitted” at any time — a folder backup cannot carry that.
Good question. Here are the five things research really needs. Press the buttons yourself and see how many of them each of the three tools can do:
The AI tools you have been using lately (Claude Code, GitHub Copilot and the like) run Git all day long behind the scenes — saving, opening branches, comparing differences are their daily routine. An AI agent editing a dozen files in one go is normal, and without Git as a safety net you cannot even say what it just changed.
The AI knows the commands, so you do not have to memorize them. But it can edit the wrong file, work on the wrong branch, or upload something that should never have left your computer. If you do not understand the concepts, all you can do is accept whatever it hands you; once you do understand them, you can read its plan, verify its diff, and stop its dangerous moves. What this course teaches is the language for directing and supervising an AI.
Items 1 and 2 take about 30 minutes. Items 3, 4, 5 and 8 involve downloading and installing (6 and 7 do not), which can take an hour or more depending on your connection. Item 5 is for Windows only; on a Mac, skip it.
If you get stuck, do not push through alone — just ask the AI. Once Antigravity is installed (item 3), ask it directly: paste the error message or a screenshot into the input box and ask it to walk you through step by step. Before that, ask whichever AI assistant you already use (ChatGPT or Gemini are both fine).
These ticks are only for you — finish with the self-check in item 10. (They are stored in this computer's browser, so they are still there after you close it.) Done so far: 0 / 10
warmup-check/hello.md really is on your desktop with the right contents; ③ you can say that the gh account the AI assistant reported is your GitHub account.| Backup and extras | What it is for |
|---|---|
| Gemini CLI (Google) | Backup (only for people already comfortable with a terminal): the command-line version, usable with the same Google account. If terminals are not your thing, do not take this route — if Antigravity will not install, use the escape hatch at the top of the setup pack: come 20 minutes early on the day and we will fix it |
| GitHub Copilot | A gift for afterwards: once you pass GitHub Education verification you can use Copilot Pro free of charge (approval takes days to weeks; the pre-class email starts the application at the same time) |
| Claude Code (Anthropic) | The instructor's demo machine: used for the opening and the “stop it in its tracks” demonstration, which also shows you the same Git concepts through a different agent |
[The classroom material starts here] We walk through the sections below together in class; if you want to prepare beforehand, start reading from here.
Three lines per card: what it is in plain words, what it looks like in everyday paper writing, and when an AI agent uses it. Click a card to open it; for the actual operations, go back to the matching P1–P9 and C1–C6 steps.
Tag: pin a memorable name on one particular save point, for example v1.0-submission. Put a tag on it the day you submit, like a label on the spine of the bound copy, and six months later, when the reviews come back, one sentence takes you back to the complete state of the project at submission.
Terms marked ◆ only have to be understood, not used. The right-hand column takes you to the step where you practice it; anything marked “extra” is not part of the classroom work.
| Term | In Git | In one line | Where it appears |
|---|---|---|---|
| AI assistant ◆ | agent | the AI you are using, which can look inside your working folder and run commands for you; in this material “AI assistant” and “agent” mean the same kind of tool | throughout |
| Terminal ◆ | terminal | the black window you type commands into — in this course the AI assistant types for you, so you never have to open it | behind the scenes |
| Markdown | .md | a plain-text file you can open and edit; the formatting goes about as far as “put a # in front of a heading” | P3 |
| Repository | repository (usually shortened to repo) | a folder plus its complete record of changes | P1 |
| Main line ◆ | main | the default line that holds the official version | P2 |
| Commit | commit | a save point with a note on it | P4 |
| Staging area ◆ | index / staging area | a snapshot of the content the next commit will save — not just a list of file names | P4 |
| Working area ◆ | working tree / working directory | the files you can actually see and are editing right now | throughout |
| Difference | diff | a line-by-line comparison between two versions | P6 |
| History | log | the timeline of save points | P8 |
| blame ◆ | blame | who changed this line, on which day, and why | P8 extra |
| View an old version | show | read the content of an old commit directly, without switching branch and without changing your current files | P9 |
| Restore a working file | restore | overwrite files in the working area or the staging area from a source you name; it can discard changes you have not committed | P9 |
| Undo a version | revert | add a new commit that does the opposite, keeping the original mistake on the record | P9 |
| Reset ◆ | reset | move where you currently are in the history, and depending on the mode also line the staging area and the working area up with it; this course only teaches you to spot the risk, not to run it | P9 safety note |
| HEAD ◆ | HEAD | points at the commit you are on now; it does not include changes you have not committed | P9 safety note |
| First parent ◆ | HEAD~1 | the first parent commit of HEAD; in a straight-line history you can read it as “the previous version” | P9 safety note |
| Remote | remote / origin | the copy that lives on GitHub; origin is its default name | P2 |
| Push | push | upload the history on your own machine to the remote | P5 |
| Pull | pull | fetch what is new on the remote and line up with it | C5 |
| Clone | clone | take a copy of a whole repository, history included, onto your own computer | C1 |
| Branch | branch | a parallel draft line for trying things without touching the real manuscript | C2 |
| Merge | merge | bring the work done on a branch back into the main line | C4 |
| Fast-forward ◆ | fast-forward | a straight-line merge when the main line has not moved, leaving no fork behind | C5 extra |
| Conflict | conflict | both sides changed the same line, so Git stops and asks a person to decide | Collaboration |
| Pull Request | PR | the formal proposal that says “I am done, please look at it before you merge it in” | C2 |
| Review | review | leaving comments on the matching lines inside a PR | C3 |
| Collaborator | collaborator | someone you have given read and write access to the repo | C1 |
| .gitignore | — | names which untracked files should stay out of version control; it is not a secrecy tool, and it does not remove files that are already tracked | P2 |
| Tag | tag | pin a memorable name on an important save point | extra |
| replication package | — | the reproducible data and code bundle journals ask for | extra |
| gh ◆ | GitHub CLI | the tool the agent uses to operate GitHub | setup pack |
| Two-factor authentication | 2FA | signing in needs a code from your phone as well as a password | setup pack |
The 15 steps below use the same numbering, goals and completion criteria as the classroom quest, but they do different jobs: the quest page walks you through it, this material helps you understand it. Each step says why you need it, which state Git is dealing with, which new terms turn up, and what you have to judge; the full text to give the AI, the plan and the commands behind the scenes are tucked into “Practice reference”, ready whenever you want them.
lin) — because it later becomes part of a branch name, so do not use characters outside the Latin alphabet. A paired repo can be written as advisor-account/thesis-pair-03, and your partner's tag might say chen. These are only format examples; the quest page does not pre-fill the repo. In C1 the advisor role creates it live, and then you fill in the actual owner/repo they report back.When two people change the same line, Git stops and waits for a person to decide; this is called a merge conflict. The AI can lay both sides out, but it cannot decide the content for a researcher.
Scenario
You and your partner both rewrote the same concluding sentence in paper.md. Your partner's version reached the main line first, and the moment you say “merge mine back in”, the agent stops.
Three steps to settle it: one, ask the agent to read both versions out side by side; two, you decide — keep one side, or dictate a new sentence to it; three, the agent finishes the merge and commits, and the conflict is gone. That is all there is to it. A conflict is not a fault; it is two authors' opinions laid out on the table, waiting for someone to judge.
If you open that file yourself you will see <<<<<<< and ======= bracketing the two versions — the file is not broken, that is Git putting both sides side by side for you.
If time allows in class, the instructor will deliberately have two people edit the same line, set the conflict off live, and let the whole class watch one being settled (if time is short we drop it; reading this page is enough on its own). Once you have seen it happen, it will not rattle you next time.
Every change in C2–C6 goes “branch → PR → someone reads it → merge in”. But who gets to press merge and put something into the real manuscript is actually a setting on the door of main. Same collaboration, and the door can be locked tighter and tighter:
Setting one, “wide open” — nothing configured. The PR is a courtesy everybody agreed on: collaborators look at each other's work and merge it themselves. Good for co-authors who already have an agreed process and trust each other completely.
Setting two, “PR required” — turn on “changes to main must go through a PR”. Nobody can quietly edit the real manuscript, and every change leaves a record that was laid out in the open; but once you have raised your hand you can merge it yourself, without waiting for anyone. Good for a team that wants everything to leave a trace.
Setting three, “approval required” — add one more rule: “1 approval before the merge button lights up”. The paired repo you build live in class runs on setting one plus classroom discipline: C3 states plainly that the other person reviews it line by line and that authors may not approve themselves — that lock is in the agreement, not on the door. When you work with graduate students on real research afterwards, we suggest turning the door up to setting three: GitHub does not let you approve your own PR, so a student's PR always needs the advisor's nod, and the whole supervision trail (who changed what, and why a change was asked for) stays inside the PR and can still be read six months later.
⚠️ Setting three needs one extra box ticked: the owner and the admins of a repo can bypass the rule by default and merge anyway, so as well as “Require a pull request before merging” and “Require approvals: 1”, also tick Do not allow bypassing the above settings — only then does the door really lock for you too.
Where to set it: the repo's Settings → Branches, add a rule for main and tick the three options above (PR required, 1 approval, no bypassing); you can change it any time. ⚠️ An honest warning: using these gates on a private repo takes more than the free plan (on a public repo they are free) — but if you apply for the GitHub Education teacher plan mentioned in the pre-class email, you get the paid features.
This section says the same thing as section 05: what you trust and what you lock is your decision — the only difference is that this time the lock sits on GitHub's door rather than in the agent's permissions.
1. Read the plan before it acts. Before it starts, the agent says “here is how I plan to do it, and why”; if that paragraph did not make sense to you, ask — you only let it run once you understand it, and if the explanation does not hold up, it does not get to act.
2. Read the diff after it acts. The agent saying it is finished does not count; it counts once you have run your eye over the line-by-line differences. Treat it exactly like reviewing your own student's revision.
These three rules are the same thing as the permission settings in item 7 of the setup pack: let commands run automatically so the class moves, keep “ask me first” for files outside the working folder, and never choose Turbo mode. You are the one who set it, which means what you delegate and what you check yourself is your decision.
3. Destructive actions: the agent has to ask you first. The list of red-line verbs: force push, resetting a branch to an old commit, hard reset (reset --hard), rewriting history (rebase), deleting files or branches, overwriting the remote, overwriting a file the old way (git checkout -- filename, which works like restore and equally wipes changes you have not committed), and clearing untracked files (git clean, which deletes exactly the things Git has not started protecting yet, and they do not come back). reset --hard lines the staging area and the tracked working files up with the target commit, so uncommitted changes are overwritten; other reset modes, pointed at an old commit, also move your local history. Whenever you see one of these verbs, call a halt and ask: which layer does this touch? Could anything be lost? Has this history already been shared? Is there a safer way? If it did any of them without asking, change its settings — or change your agent.
4. Student personal data and unpublished material never go into a public repo. Grade sheets, class lists, manuscripts still under review: never in a public repository. Research collaboration should use a private repo, and even then you check file by file before anything goes public. .gitignore can only help keep untracked files out; it does not replace your judgment about the data, or your access controls.
5. No passwords in a private repo either. Once a password or an API key has been committed it is in the history, and deleting the current file afterwards does not make the old record disappear. Keep sensitive material outside the project folder; for settings that are not sensitive but only meant for your own machine, use .gitignore.
First, stop: do nothing else, and above all do not push. Second, check: ask the agent “did that file get into the repository? has it been pushed to GitHub?” Third, deal with it: if it has not been pushed, paste this to the AI assistant — “Which commits has that file been in? Please clean it out of every one of them, add the file name to .gitignore, and verify it again for me afterwards. Do not push yet.” (Cleaning only the last commit often does not do the job, so ask it to check them all.) If it has already been pushed, treat it as a leak: change the password inside it, tell the people concerned, and get someone who knows what they are doing to help clean the history (you can clean your own copy, but not the copies other people have already taken).
By the way: GitHub automatically blocks common key formats in public repos — when a push is stopped by “secret scanning”, do not look for a way around it, because that is red line 5 saving you.
When you create a new repo, check two things while you are there: set visibility to Private — anything containing student data is private, no exceptions; and if you mean to share teaching material publicly, remember to choose a license so other people know what they may do with it.
Twelve sentences you really will say. Press “Copy” to paste one straight into the agent's chat box and try it.
The task sentences for the day are all on the quest page, ready to copy. This table is your everyday phrasebook for when you go back to your own research — it is also what the printed reference card contains. The other quick reference, “what I want to do → how to say it”, is in the plain-language lookup in “SOS”; the two complement each other and do not repeat each other.
⚠️ One phrasing to be careful with: “go back to the previous version” is ambiguous to an agent — it cannot tell whether you mean “I just edited it and have not saved”, “I saved it and want to undo that”, or “delete the last three versions”, and if it reads you wrong it may lose work you never saved. Use the sentence patterns in the table below to make the situation clear, or have the agent repeat its understanding back to you before you let it run.
| You say | What the agent does | The concept behind it |
|---|
Table not matching your situation? Fill in the blanks in this general SOS sentence and paste it to the AI — it is “look first, plan next, act last” in portable form:
You can hand these sentences straight to the AI. For anything that touches your files or your history, still read the plan and the diff first. The 12 situation-based everyday sentences are in “06 How to talk to the agent”; this one is task-based, and the two complement each other.
| What I want to do | How to say it |
|---|
Your score so far: 0 / 9
The minutes marked on each step are an estimate for one person working smoothly. The schedule below merges neighboring steps and keeps 0:56–1:02 as shared slack, so the rows do not add up step by step. 1:16–1:41 (C2–C5) is the only stretch of the day with no slack — that is where the two of you have to wait for each other, so if it runs over, borrow from 1:50–1:56.
The last column is live feedback (participants use their phones to rate difficulty, ask questions and vote). If that service is not deployed, skip the whole column; the course runs exactly the same without it. The question numbers are the seven self-check questions on the participant page, and the first part tells you which part of the course they belong to (pre = before class, 1a/1b = Stage 1, 2a/2b = Stage 2, 3a/3b = wrap-up). All seven are visible the whole time, but the participant page grays out the ones that have gone past and marks them “no need to catch up”.
| Time | What the room is doing | Steps | What the instructor watches for | Live feedback (optional) |
|---|---|---|---|---|
| Before class (arrival) | The live-feedback QR code is on the projector; participants scan it and vote “pre” | — | Read the spread of “pre” votes to decide how much detail the opening needs | vote “pre” |
| 0:00–0:08 | Opening: version chaos, who does what between the AI and you | Roadmap | Cover the red lines first; do not teach command memorization | One reminder: keep the phone on the desk as a call bell, and press the difficulty button when you are stuck |
| 0:08–0:14 | Create an ordinary folder and open it in Antigravity | P1 | Check everyone is on the same working path | 1a stays open; update it as you change steps |
| 0:14–0:22 | Add Git and .gitignore, create and connect the GitHub repo | P2 | Confirm there is nothing but fake data before anything goes public | 1a stays open |
| 0:22–0:31 | Create notes.md, look at the status, first commit | P3–P4 | Always look at the file and the diff before committing | 1a stays open |
| 0:31–0:40 | First push; let the AI make a small edit and read the diff | P5–P6 | Read the plan before the edit, check it line by line afterwards | 1a stays open |
| 0:40–0:47 | Second commit and push | P7 | Keep commit and push clearly apart | 1a stays open |
| 0:47–0:56 | History, comparing versions, restore and revert | P8–P9 | Stop and confirm at every step that changes something | 1a stays open |
| 0:56–1:02 | Catch-up time for the individual stage | Minimum-line check | 2 commits + 2 pushes | Vote 1b; check 1a for anyone still stuck near the start |
| 1:02–1:06 | Break, pair up, hand out role cards, exchange GitHub account names | Pairing | Write the accounts on the back of the role card; C1 needs them immediately | Vote 2a |
| 1:06–1:16 | C1: the advisor creates the paired repo; the student accepts the invitation and clones it (a second folder) | C1 | The advisor keeps the folder just created instead of cloning again; both people need WRITE access; point the quest page at the new folder. Stuck for more than 5 minutes = put them straight onto the demo repo | Watch 2a for anyone stuck “waiting for the invitation to be accepted” |
| 1:16–1:41 | Round one: the student opens a PR; the advisor asks for changes; after the revision, approve and merge; both pull | C2–C5 | The other person looks at Files changed themselves; authors may not approve their own work | 2b stays open |
| 1:41–1:50 | Swap roles and run one short round | C6 | The diff and the other person's approval cannot be skipped | 2b stays open |
| 1:50–1:56 | After the second merge, both do a final pull, look at the history, troubleshooting | C6 wrap-up + rescue | Both computers can see the latest content of main | 2b stays open |
| 1:56–2:00 | Understanding check, recap, and what to take home | Wrap-up | Can state who does what between the AI and you, and the three red lines | Vote 3a, and 3b in the last minute |
The paired repo is now built live by the participants in C1 (the advisor's AI creates it in one sentence, and the student accepts the invitation themselves), so the instructor does not have to build it in advance. What you do need: role cards — the group number and the first-round role on the front, and two blank lines on the back, “my GitHub account / my partner's GitHub account”, for the pair to copy from each other; a way of pairing — we suggest pairing neighbors, and with an odd number, make the last group a three and let the third person be the student in the second round in C6; and one instructor demo repo — built beforehand to the C1 specification (paper.md containing “Method” and “Literature review”, and .gitignore excluding WORKSHOP-RECEIPT*.txt). If a pair is stuck on C1 for more than five minutes, add both of them as collaborators on the demo repo (have them accept the invitation themselves and confirm the permission is WRITE, otherwise the push in C2 will fail), let them clone that one and carry on with C2, and build their own afterwards.
If one participant's AI tool or network gives out: have them follow along on the GitHub website instead (edit and commit in the browser; reviewing and merging a PR happens on the website anyway), and no concept is lost. Only a room-wide failure calls for the instructor to demonstrate on the projector.
We put this list together after actually working through 18 Git courses on the web (July 2026). Every entry says where to start reading, because you have an agent typing the commands for you and many chapters can simply be skipped.
| If this is you | What we recommend | Where to start |
|---|---|---|
| You would rather review the concepts in Chinese | “Even a monkey can understand Git” (in Chinese) | Read part one up to “undoing changes” and stop; skip the whole hands-on part (it is written for people typing the commands themselves); go to the troubleshooting pages when you get stuck |
| “Learn Git for yourself” (in Chinese) | Skip the three chapters on installing and on the terminal and start at “working area, staging area and repository”; treat the scenario chapters as a first-aid kit for when things break | |
| You do empirical work in R or Stata | EC 607 Lecture 2 (02-git inside the repo) | A syllabus written by an economist for economists; start at the section on the Git panel in RStudio |
| Software Carpentry git-novice | Aimed at researchers; the Open Science / Licensing / Citation episodes are in no other course | |
| You want something systematic, or a certificate | Microsoft Learn: GitHub Foundations (Traditional Chinese edition) | Free, and reading it through gives you the whole system; the certification exam costs money and is not offered in Chinese, so most people need not take it. Note that this edition uses Microsoft's own translations of the terms, which differ from the ones used here |
| edX IBM: Git and GitHub Basics | Free to audit, browser-based labs all the way through, and you finish with a public repo | |
| You want to go deeper into how it works | MIT Missing Semester: Version Control | Start at the “data model” section — get the mental model first and you never have to memorize commands |
| Learn Git Branching (Traditional Chinese edition) | Do the four basic levels and stop; you will not need the later ones |
Background reading with an economics slant: Michael Stepner, git vs. Dropbox (the best pre-class reading) | Frank Pinter, Git: A Guide for Economists | Arthur Turrell, Coding for Economists | AEA Data & Code Policy and the AEA Data Editor guidance.
stash, rebase, amend, fork workflows, GitHub Actions, Git internals — courses written for researchers agree on skipping all of them at the beginner stage, and we follow suit. The reason in one line: when you need them, your agent knows how, and you only have to be able to read its plan. This “you can leave it” list matters as much as the “you should learn it” list before it — it is what makes a two-hour scope hold together.
1. Word and Excel do not show line-by-line differences in Git. They are not plain-text files, so a diff only says “the file changed”, never which line changed. Git is at full power with plain-text files (.md, .R, .do, .tex, .csv). You can still keep Word files in a repository for backup and syncing; it is the “track changes” experience that stays Word's own job.
2. GitHub Free allows branch protection rules on public repos, while what is available on private repos depends on the account and the organization plan. This course practices review in a public repo full of fake data. For real research data, judge first whether it can be public; never make sensitive data public just to unlock a feature. Please check GitHub's official documentation and the accounts in the room again before you teach it.
3. Agents make mistakes, which is exactly why the concepts matter. An agent may edit the wrong file, write the wrong explanation, or start working on a branch you did not want touched. You do not have to memorize commands, but you do have to be able to read its plan and its diff — the concept map earlier is what makes you its thesis advisor rather than its rubber stamp.