ETC5513: Collaborative and Reproducible Practices

Tutorial 6

Author

Michael Lydeamore

Published

6 April 2025

🤝 Workshop: Forking, Branching, and Rebasing with Quarto

In this workshop, you’ll practice collaborative editing using branches, rebasing, and pull requests in a Quarto project.

You’ll simulate a real-world collaboration scenario: - One student makes changes to the main branch - Another student works on a feature branch - Before contributing, the second student rebases to keep history clean

🧑‍🤝‍🧑 Step 1: Pair Up

Assign roles:

  • Student A = Repository owner
  • Student B = Contributor

You’ll swap roles after completing the exercise.

🛠️ Step 2: Student A – Set Up the Repository

  1. Create a new GitHub repo named something like quarto-rebase-demo
  2. ✅ Add a README file
  3. Clone it locally:
git clone git@github.com:your-username/quarto-rebase-demo.git
cd quarto-rebase-demo
  1. Create a Quarto file called collab.qmd:
---
title: "Rebase Demo"
format: html
---

# Introduction

This is a collaborative Quarto project.

# Contributions

<!-- Student sections will go here -->
  1. Commit and push:
git add collab.qmd
git commit -m "Add initial Quarto file"
git push origin main
  1. Share the GitHub link with Student B.

✅ Student B can now fork the project.

🍴 Step 3: Student B – Fork, Branch, and Contribute

  1. Fork Student A’s repository on GitHub
  2. Clone your fork:
git clone git@github.com:your-username/quarto-rebase-demo.git
cd quarto-rebase-demo
  1. Create a new branch for your work:
git branch my-section
git switch my-section
  1. Open collab.qmd and add your section under “# Contributions”:
# Jamie’s Section

This is my contribution to the Quarto project.
  1. Save the file, then stage and commit:
git add collab.qmd
git commit -m "Add Jamie’s section"

✅ Don’t push yet — Student A will now make another change.

🧱 Step 4: Student A – Make Another Commit on main

While Student B is working, Student A adds a new section to collab.qmd:

# Instructor's Section

This section was added after Student B began work.
  1. Save the file, then commit and push:
git add collab.qmd
git commit -m "Add instructor’s section"
git push origin main

✅ Now Student B’s branch is behind main.

🔄 Step 5: Student B – Rebase Onto Latest main

  1. Add Student A’s repo as a remote:
git remote add upstream git@github.com:student-a-username/quarto-rebase-demo.git
git fetch upstream
  1. Rebase your branch:
git rebase upstream/main
  1. If there are any conflicts, Git will pause and show them in collab.qmd. Edit the file and resolve them manually. It might look like this:
<<<<<<< HEAD
# Jamie’s Section
This is my contribution to the Quarto project.
=======
# Instructor's Section
This section was added after Student B began work.
>>>>>>> upstream/main
  1. After fixing the file, run:
git add collab.qmd
git rebase --continue
  1. Once rebasing is complete, push your changes to your fork:
git push origin my-section --force
Caution

Any command with --force is dangerous as it can rewrite the history of the repo. In this case, this is exactly what we want, but run the command carefully.

✅ Step 6: Create a Pull Request

  1. Go to your fork on GitHub
  2. Click “Compare & pull request”
  3. Make sure your PR is from my-section → main (on Student A’s repo)
  4. Click Create pull request

✅ Your rebased contribution is now ready for review!

📬 Step 7: Student A – Review and Merge

  1. Open the pull request
  2. Check the changes
  3. Click Merge pull request → Confirm merge

🎉 Now the main branch has clean history and includes both contributions!

✅ Summary

You now know how to:

  • Fork and clone a GitHub repository
  • Work on a feature branch
  • Rebase changes onto the latest main
  • Submit a clean pull request

✨ You’ve just used a professional Git workflow!