Workshop | Git & GitHub

This repository contains all materials for the Git & GitHub workshop, including the presentation slides, workshop notes, hands-on exercises, and setup instructions.

Note

Please complete the steps in the preparation guide⁠ before the workshop. This allows us to spend more time on hands-on exercises and less time troubleshooting software installations.

Repository Structure

.
├── AGENDA.md                # Facilitator guide: schedule, breaks, cut list, checklists
├── CHEATSHEET.md            # One-page command reference for participants
├── preparation.md           # Workshop setup instructions – do this before day one
├── preparation-optional-signing.md
├── workshop/
│   ├── core/                # Written notes – start at workshop/README.md
│   └── intermediate/        # Follow-on material, not covered in this workshop
├── exercises/
│   ├── core/                # Hands-on labs matching the core chapters
│   └── intermediate/
├── slides/                  # Slidev deck; presenter notes carry the facilitator script
├── handson-upstream/        # Seed for the hands-on repository (instructor only)
└── README.md

Start at workshop/README.md. Chapter filenames are not numbered, so that page – not the directory listing – is the reading order, with each chapter's exercise and estimated duration alongside it.

The written notes in workshop/ are the source of truth. The slide deck condenses them, and each section slide links back to its chapter. If the two ever disagree, the notes are right.

Each chapter carries frontmatter with its tier, its estimated duration, its exercise, and its learning objectives, so AGENDA.md can be checked against the material. Every chapter also ends with a Check yourself section, and CHEATSHEET.md condenses the whole command set onto one page.

The facilitator script lives in the deck's presenter notes – every slide carries its purpose, the transition into it, any live demo, and the misconception to expect. Press P while presenting. AGENDA.md is the block-level companion to it.

Git & Collaborative Version Control

Background

Version control is an essential tool for modern software development, research, and collaborative projects. It allows you to keep track of changes, work together with others, and safely experiment without losing previous work.

Git is the most widely used version control system, while platforms such as GitHub and GitLab make it easy to collaborate, review changes, and share projects. Although this workshop uses GitHub for demonstrations, the concepts and workflows apply equally to GitLab and other Git hosting platforms.

Format

This is a hands-on workshop that combines short presentations with practical exercises. Participants will work on their own laptops throughout the session and are encouraged to follow along with every example.

It runs over two days: 8 hours on day one and 2 hours on day two, 10 hours in total including breaks. Day one is entirely local – from the terminal to branches. Day two is one real contribution to a repository you do not own. See AGENDA.md for the block schedule.

No previous experience with Git or the command line is required. All essential concepts and commands will be introduced step by step.

Workshop Topics

During the workshop, participants will learn how to:

• understand why version control is useful
• navigate the command line and use basic terminal commands
• create and manage Git repositories
• record, review, and organize changes with Git
• inspect project history, and undo changes safely at every level
• recover work after a mistake, using git reflog
• work with branches and merge changes, including resolving conflicts
• collaborate using GitHub: forks, pull requests, review, and revision
• read and act on an automated check that fails on a pull request
• see what changed before committing it, with git diff and git diff --staged
• fix the last commit with git commit --amend instead of starting over
• write project documentation using Markdown
• follow best practices for collaborative and reproducible projects
• record AI assistance and co-authorship transparently in commit history

Practical exercises are integrated throughout the workshop to reinforce each topic.

On AI-assisted development: the workshop does not demonstrate AI tools writing code or commits. What it teaches is the git-native side – how to disclose that kind of help in your commit history using trailers such as Co-authored-by: and Assisted-by:, and why that transparency matters for attribution and reproducibility. See Modern Tooling and Disclosure.

Learning Objectives

By the end of the workshop, participants will be able to:

• explain the purpose and principles of distributed version control
• use Git to manage the history of code, documents, and research materials
• create and manage repositories with confidence
• collaborate effectively using GitHub or similar Git hosting platforms
• apply branching and merging workflows in collaborative projects
• contribute to transparent and reproducible research and software projects

Prior knowledge

This workshop is designed for beginners. No prior experience with Git, GitHub, or version control is required.

Basic computer skills are sufficient. Familiarity with using a command-line terminal is helpful but not expected, as all required commands will be introduced during the workshop.

Requirements

Please ensure you have the following before the workshop:

• A personal laptop (Windows, macOS, or Linux)
• A GitHub account
• A stable internet connection
• The workshop environment set up by following the preparation guide

Warning

If you encounter any issues during the setup, please contact me before the workshop so they can be resolved in advance.

Not covered in this workshop

The intermediate material is kept in this repository but is deliberately not taught during the two days:

• Rebasing, interactive rebase, and squashing. Day one ends with a short look-ahead and a pointer instead. Rebase rewrites history, and it deserves its own session rather than the last twenty minutes of a long day.
• Line endings and .gitattributes. The symptom – a file that will not stop looking modified – is a beginner problem, and its first section is written to be read on its own. The fix is a policy set for a whole repository, which is not a beginner's decision.

Further Reading

Documentation

• Git documentation git-scm.com/doc
• GitHub documentation docs.github.com/en
• GitLab documentation https://docs.gitlab.com/

Additional Resources

• This workshop's one-page reference CHEATSHEET.md
• Oh shit, git!?! ohshitgit.com
• Oh my git ohmygit.org
• .gitignore generator www.gitignore.io