Week 5: Quarto & Collaborative Coding
2026-05-13
Practical directly after lecture today!
The practical will be directly after the lecture today in the same room (S004).
Part 1: Statistical Programming Foundations (W2–6)
penguins-project/ ← repo root = RStudio project
├── penguins-project.Rproj
├── README.md ← dataset, research questions, members
├── CONTRIBUTING.md ← contribution statement + AI disclosure
├── _quarto.yml ← renders the whole repo as a Quarto website
│
├── data/
│ ├── raw/ ← read-only; never edited by scripts
│ │ ├── penguins.csv
│ │ └── LICENCE.txt ← data licence documentation
│ └── processed/ ← output of cleaning scripts
│ └── penguins_clean.csv
│
├── code/
│ ├── 01_download.R ← optional: script to fetch raw data
│ ├── 02_clean.R
│ ├── 03_eda.R
│ └── 04_analysis.R
│
├── docs/ ← rendered Quarto outputs (auto-generated)
│
├── proposal.qmd ← due Jun 8
├── report.qmd ← final output (or index.qmd for website)
└── .gitignore Note
Due Mon 8 Jun — submit link to your rendered webpage (not Quarto document) on Moodle
1. Dataset & research questions
2. Initial data analysis
glimpse() and summary statistics3. Analysis plan
How do you plan to answer your research questions?
4. Workflow organisation
styler, shared AI system prompt)?renv (W9) to lock versions?.gitignore: What will you exclude (data files, rendered outputs, secrets)?Tip
You do not need answers yet — show that you have thought carefully about what is feasible with your data.
Browsing the log
| Goal | Command |
|---|---|
| Compact history | git log --oneline |
| Commits on a file | git log -- <file> |
| Full diff of a commit | git show <hash> |
.gitignore
*.csv, _site/, .env)The remote loop
GitHub ──clone──▶ local (once)
GitHub ──pull───▶ local (start of session)
local ──push───▶ GitHub (end of session)From StatProg1
A .qmd file has three components:
--- delimiters)```{r} and ```Chunk options go on #| lines at the top of each chunk.
Text formatting
Tip
Switch between Source and Visual mode in RStudio with Ctrl+Shift+F4 — Visual mode renders markdown live.
How rendering works
.qmd → knitr (R) / jupyter (Python) → .md → pandoc → HTML / PDF / docxRender to final output
Tip
Use quarto preview while writing — it re-renders on every save so you see changes instantly.
What is the difference?
For your analysis
.qmd files diff and merge cleanlyFor your audience
Quarto projects are directories that provide:
.qmd files with one command: quarto renderoutput-dir)There are three ways to start a Quarto website project:
quarto create project > website_quarto.yml to an existing repositoryRender to output-dir
Output goes to docs/ (or whatever output-dir is set to).
Navigation under website: in _quarto.yml:
See quarto.org/docs/websites/ and the Website Options Reference for the full list.
You can share YAML options between files in the same project by specifying them in _quarto.yml. For example, you might want to set some project level code display and execution options:
Code display — under format: html:
A website is just files
quarto render produces website files — e.g. in _site/ or docs/quarto preview serves them locally at http://localhost:NNNNTo reach the world, you need a host
GitHub Pages
GitHub pages is a free hosting service — it serves the contents of a branch (or folder) in your repo as a website at https://<user>.github.io/<repo>/
_site/ to .gitignore (rendered output goes to gh-pages branch, not docs/)gh-pages branch:https://<user>.github.io/) you must manually switch the source branch to gh-pages under Settings → Pages after the first publish.What happens under the hood
gh-pages branchgh-pages automatically.qmd files stay on main — gh-pages only ever contains rendered HTML.quarto publishDrag & drop deploy
index.html) onto the pageOr publish from the terminal:
The metaphor
A branch is like writing two drafts of a chapter at the same time.
main is your published, working draftmainThe reality
A branch is just a named pointer to a commit.
Scenario: Adding a species filter without breaking working code on main.
gitGraph commit id: "Initial commit" commit id: "Add data cleaning" branch feature-penguin-filter checkout feature-penguin-filter commit id: "Add species filter" commit id: "Test filter logic" checkout main commit id: "Fix README typo" %% merge feature-penguin-filter id: "Merge filter"
Tip
Name branches after what they do: add-penguin-filter, fix-missing-values, week4-reflection.
Create & switch
Inspect & tidy up
The metaphor
Merging is like combining two edited drafts of the same chapter.
Two kinds of merge
main hasn’t moved since the branch split; git just advances the pointer, no merge commit neededScenario: feature-penguin-filter is finished; and we didn’t edit main!
gitGraph commit id: "Initial commit" commit id: "Add data cleaning" branch feature-penguin-filter checkout feature-penguin-filter commit id: "Add species filter" commit id: "Test filter logic" checkout main commit id: "Fix README typo" type: REVERSE merge feature-penguin-filter id: "Fast-forward ✓" commit id: "Continue on main"
Scenario: feature-penguin-filter is finished; bring it into main via Three-way merge.
gitGraph commit id: "Initial commit" commit id: "Add data cleaning" branch feature-penguin-filter checkout feature-penguin-filter commit id: "Add species filter" commit id: "Test filter logic" checkout main commit id: "Fix README typo" merge feature-penguin-filter id: "Merge filter"
main now contains every commit from both lines.
Merge a branch
Inspect merges
Tip
Always be on the target branch (e.g. main) before running git merge.
The metaphor
You’re mid-task at your desk when your supervisor drops by with an urgent request.
The gotcha
git stash push -m "description" to label themgit stash pop restores and removes the top stashgit stash apply restores but keeps it in the listScenario: Half-way through a feature when a bug is reported on main.
Save & restore
Inspect & clean up
Tip
Always label stashes with -m — a stack of anonymous stashes is surprisingly easy to lose track of.
The metaphor
Normally you have one desk (working directory) per repo.
git worktree sets up a second desk in a different folder — each desk has a different branch checked out, but both share the same filing cabinet (.git).
When stash isn’t enough
Scenario: feature-eda is half-done in ~/project/; an urgent fix is needed on main.
Both folders are live — edit one without touching the other.
Set up & use
Inspect & clean up
Tip
For most day-to-day interruptions, stash is enough. Worktrees shine when you need two branches open for an extended time.
The flow
GitHub ──clone──▶ local
GitHub ◀──push─── local
GitHub ──pull──▶ localConnect & inspect
The metaphor
Two co-authors both rewrote the same sentence in their own copies — now you need to decide which version (or a blend) to keep.
When they happen
git pull brings in remote changes that clash with local editsgit merge joins histories with overlapping changesConflicts happen when the same lines are changed in two places before syncing:
Edit on GitHub.com (online editor or Codespaces) while you also have local edits — git pull will flag a conflict.
gitGraph commit id: "shared base" branch origin/main checkout origin/main commit id: "edit on GitHub.com" checkout main commit id: "local edit" merge origin/main id: "CONFLICT ⚠️" type: HIGHLIGHT
Resolution is the same:
git pull — git downloads and tries to merge<<<<<<< markersgit add <file> then git commitWhat happens when you?
README.md on Github.commainREADME.mdmaingit pullTip
What is different between the two “Commit changes directly to main steps?”
Git inserts conflict markers directly into the file:
<<<<<<< HEAD
result <- mean(x, na.rm = TRUE)
=======
result <- median(x, na.rm = TRUE)
>>>>>>> feature-branch<<<<<<< HEAD — your version (current branch)======= — divider between the two versions>>>>>>> feature-branch — incoming versionTip
In RStudio: open the file in the editor — conflict regions are highlighted with accept/reject buttons.
<<<<<<<, =======, >>>>>>>)git add <file> — mark as resolvedgit commit — complete the mergeTip
Small, focused commits and frequent pulls keep conflicts small and easier to resolve.
Scenario: Two teammates both edit report.qmd directly on main at the same time.
gitGraph commit id: "shared base" branch teammate checkout teammate commit id: "adds plot section" checkout main commit id: "rewrites intro" merge teammate id: "CONFLICT ⚠️" type: HIGHLIGHT
Tip
Avoid mega-documents. The project template splits work into separate files (02_clean.R, 03_eda.R, report.qmd) — teammates own different files and conflicts become rare.
DO
main clean — only merge finished, working codeDON’T
main at the same timeTip
Branching friction is productive — it forces you to think in small, independent tasks.
In a group project, multiple people work on different parts at the same time — pull requests are the mechanism for bringing that work together safely.
Without PRs
mainWith PRs
main stays stable and deployableTip
Think of a PR as a conversation: “here’s what I did, and here’s why” — it creates a permanent record alongside the code.
gitGraph commit id: "existing work" branch my-feature checkout my-feature commit id: "add EDA plot" commit id: "clean up code" checkout main merge my-feature id: "PR merged ✓" commit id: "continue on main"
git switch -c my-featuregit push -u origin my-featureIn order to open a pull request, you need to push your local branch to GitHub:
The -u flag links your local branch to origin/my-feature — after that, plain git push and git pull know where to go.
Tip
After pushing, GitHub shows a banner: “Compare & pull request” — click it to open a PR.
Continuing from the group repo you forked and published earlier:
git switch -c edit-proposalproposal.qmd stub and commit itgit push -u origin edit-proposalgit switch main && git pull_quarto.yml — it renders all .qmd files and shares options across themquarto publish gh-pagescode-fold, code-line-numbers) under format: html: and execution options (echo, freeze) under execute: in _quarto.yml.qmd files_quarto.yml renders the whole repo as a website — proposal, report, and README in one placeBranches, stash & worktrees
git switch -c <name>git stash / git stash popgit worktree when you need two branches open at oncePull requests & conflicts
git push -u origin <name>, then open a PR on GitHub<<<<<<< markers, git add, then git commitTip
Pull at the start of every session, push at the end — this keeps conflicts small.