Version Control with Git

Version control tracks every change you make to a project — who changed what, when, and why — so nothing is ever lost and you can roll back to any earlier state. In this course, your version history is also how you submit your work. This section sets up Git and GitHub and walks through the core workflow.

Git and GitHub

Git is version control software that runs on your machine (or the Yens). It tracks every change you make to a project — who, what, and when — and lets you roll back to any previous state.

GitHub is a website that hosts git repositories in the cloud. It’s where you share, back up, and submit your work.

Git saves your work as commits — snapshots of your whole project at a moment in time, each with a short message describing what changed. Your history is a chain of these snapshots, and you can return to any earlier one at any time.

Each dot is one commit — a saved snapshot. The chain runs oldest (left) to newest (right).

A branch is a git feature that lets you build a separate line of commits without disturbing your main work. You branch off, commit there, and merge back when the work is ready — so a risky experiment never touches your working version.

You branch off main, make commits on experiment, then merge them back. main stays intact until you do.

The workflow for this course:

Three numbered steps: ① fork — make your own copy of the course repo on GitHub · ② clone — download that copy to the Yens, where you actually work · ③ push — send your finished work back up to your fork.

Each day’s challenge is submitted with a git push to your fork as proof of work. No push, no submission.

You’ve now met the two core git ideas — commits and branches. Two more features come from GitHub (the hosting side) and show up later in the course:

Issue — a written note attached to the repo: a task to do, a bug you hit, a question to revisit. Issues are timestamped and searchable, so they can serve as a running log if you choose to use them that way.
Pull request (PR) — a proposal to merge one branch into another. It shows exactly what changed and lets you (or a collaborator) review the changes before they become part of the main version.

Version control isn’t just bookkeeping — it offers a few concrete advantages for research:

Why version control helps research:

A readable history of what changed and why. Every commit carries a short message. Instead of guessing what a file used to hold, you scroll its history and read “clean data: drop 3 duplicate rows” right next to the exact lines that changed.

No more filename soup. You don’t need analysis_final_v2_USETHIS_edited.R to keep track of versions. There’s one analysis.R, and its history holds every past version with an explanation of each change. The filename says what the file is; the history says how it got there.

Experiment safely on a branch. Try a risky reanalysis without touching your working results. If it doesn’t pan out, the branch is a record of what you tried rather than a mess to clean up.

Project management, even if you barely write code. GitHub’s issues and pull requests aren’t only for software teams — you can use issues to track to-dos, data questions, or bugs, and pull requests to review a change before it’s merged into your main version.

Backed up and shareable. Every version is recoverable, and pushing to GitHub backs your work up and lets a collaborator — or your future self — pick it up.

Version control is powerful, but it isn’t a cure-all. A few honest caveats:

Caveats:

Git has a steep learning curve. It’s genuinely confusing for newcomers — expect to lean on notes, cheatsheets, and AI tools at first.

GitHub is a commercial product. It’s owned by Microsoft, not a community-run open project. Convenient and widely used, but not neutral infrastructure.

Git is a poor fit for versioning data. It’s built to track line-by-line changes in text and code; large or binary data files make the repository slow and bloated.

GitHub is not for datasets — especially large ones. It enforces file-size limits and isn’t meant for data storage. Keep data on the cluster (/yen/projects, /scratch) or in a data repository, not in your GitHub repo.

Exercise

Your work in this course is tracked in your version history. Set up your copy of the course repo and make your first commit now.

Exercise: Fork the course repo, clone it to the Yens, authenticate with GitHub, create a branch, commit a file, and push it back to your fork.

Step 1 — Fork the course repo, and build your site

A fork is your own copy of the course repo, living under your GitHub account. GitHub deliberately switches a few things off on a new fork, so turning your fork into a working course site takes five clicks in a particular order. Do all of them now:

Fork the repo. Go to the course repo on GitHub and click Fork in the top-right corner.
Turn on Issues. On your fork: Settings → General → Features → tick Issues. A fork starts with its issue tracker switched off, and you’ll be logging issues later today — both the github-for-research skill and the Day 1 Challenge depend on it.
Turn on Actions. Open the Actions tab on your fork. It says “Workflows aren’t being run on this forked repository” — click the green “I understand my workflows, go ahead and enable them.” This is the step everyone misses, and nothing builds until you do it.
Turn on Pages. Settings → Pages → Source → GitHub Actions → Save. (This tells GitHub how to publish; it does not lift the block in step 3, which is why both are needed.)
Build the site once by hand. Actions → Deploy Jekyll site to Pages → Run workflow. Enabling Actions isn’t retroactive, so the very first build needs a nudge. From here on, every change that lands on your main rebuilds the site automatically.

Then open your site: https://YOUR-USERNAME.github.io/gsb-research-computing-ai-skills/

This is now your course site, where your progress and leaderboard position are tracked from here on. (The first build takes a minute or two — watch it finish on the Actions tab.)

Leave the other workflow switched off. Your fork also contains Update leaderboard roster. That one is for the class repo only — it would keep overwriting your copy of the class roster every ten minutes and collide with your own work. You don’t need it: the leaderboard reads your progress directly from your fork, so ./cast (Step 7) is all it takes to appear on it.

Step 2 — Clone to the Yens

Cloning downloads your fork onto the machine you’re working on — here, the Yens.

cd ~
git clone https://github.com/YOUR_GITHUB_USERNAME/gsb-research-computing-ai-skills.git
cd gsb-research-computing-ai-skills

🟢 Green sticky = I’m done and ready 🔴 Red sticky = I need help

Put a sticky note on your laptop lid so instructors can see where you are.

Step 3 — Authenticate with GitHub (one time)

Pushing to your fork has to prove it’s really you. You’ll create a Personal Access Token (PAT) — a single-purpose password for the command line — and hand it to the GitHub CLI (gh) once. After that git just works. There’s no browser on the Yens, so a token is the simplest way in.

Create the token — do this in your browser, on your laptop:

Open this pre-filled link: Create your token. It’s a classic token with the three scopes you need already checked — repo (push to your fork), workflow (lets you push changes to the GitHub Actions files), and read:org (lets the GitHub CLI sign you in) — and named yen-repo-workflow.
Set the expiration to 1 year — long enough to reuse this token for your research work well beyond this course, with an automatic backstop if it’s ever forgotten or leaked.
Click Generate token, then copy it right away — GitHub shows it only once.

Treat the token like a password: don’t commit it, don’t paste it into a file, don’t share it. If it ever leaks, delete it on GitHub and make a new one.

Give the token to gh — on the Yens:

ml gh-cli           # make gh available on the Yens
gh auth login       # answer: GitHub.com → HTTPS → Authenticate Git → Yes → Paste an authentication token
gh auth setup-git   # let gh remember the token so git never asks you again

Paste the token when gh auth login asks. The gh auth setup-git step then wires gh in as git’s credential helper, so it hands over your token automatically on every git push — no browser, no device code, and no password prompt, now or in future sessions.

Setting up gh on your own laptop

You’ll want gh on your laptop too (for the Claude Code work later). Install it, then run the same gh auth login and paste the same token:

macOS (Homebrew): brew install gh
Windows (in PowerShell — then it’s usable from Git Bash too): winget install --id GitHub.cli
Linux / other: see the official instructions

gh auth login    # GitHub.com → HTTPS → Paste an authentication token

(On a laptop you can instead choose “Login with a web browser” — but the token works everywhere, so reusing it is one less thing to think about.)

Step 4 — Create a branch

A branch is a safe, separate workspace, so your experiments never disturb the main version of your work.

git checkout -b experiment

Step 5 — Make a change and commit

add chooses which changes go into your next snapshot; commit saves that snapshot with a message describing what changed and why.

echo "Hello from Day 1" > my_first_commit.txt
git add my_first_commit.txt
git commit -m "Add my first commit from Day 1"

Step 6 — Push to your fork

Pushing sends your saved snapshots up to your fork on GitHub — where they’re backed up and, later, where your submitted work can be checked.

git push -u origin experiment

This pushes your branch, which is not the same as updating your site. The site rebuilds only when your fork’s main changes — which happens when you cast a spell (Step 7) or merge a pull request. An experiment on a branch leaves the published site alone, which is exactly the point of branching.

Every day’s challenge is submitted the same way — a git push to your fork. Come back to these steps whenever you need to submit work.

Step 7 — Ready your spell-caster (one time)

Your fork ships with a small program called cast — your spell-caster for recording quest progress to the leaderboard. Make it executable, once, from your repo root:

chmod +x cast

From now on, whenever you check off a quest the site reveals a one-line spell beneath it — run it from your repo root to update your standing:

./cast <spell>

🟢 Green sticky = I’m done and ready 🔴 Red sticky = I need help

Put a sticky note on your laptop lid so instructors can see where you are.

Exercise complete

What You Learned

Fork, clone, branch, commit, and push with git — version-control every project from day one

Next: set up Claude Code and learn what data it can and can’t be given — see Working with Claude Code.