Rebuild Git & GitHub course as an executable self-study course

.github/workflows/quality.yml

@@ -0,0 +1,44 @@
+name: Course quality gates
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: course-quality-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate ${{ matrix.os }} / Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Validate course structure and links
+        run: python scripts/validate_repo.py
+
+      - name: Compile validator
+        run: python -m py_compile scripts/validate_repo.py
+
+      - name: Verify controlled CI demo
+        working-directory: examples/actions/demo
+        run: python -m unittest discover -s tests -v
+
+      - name: Verify Git conflict and reflog behavior
+        run: python scripts/smoke_git_behaviors.py

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for helping improve this course.
+
+This repository is a textbook and reference implementation. Learner practice belongs in a separate disposable `git-github-lab` repository unless a contribution specifically improves the curriculum itself.
+
+## Before opening a change
+
+1. Read `SAFETY.md` if the change teaches recovery, reset, rebase, force operations, or history rewriting.
+2. Keep the course beginner-accessible. Prefer a precise mental model and a small reproducible exercise over adding more commands.
+3. Do not add claims of mastery that the learner cannot demonstrate.
+4. Do not add secrets, personal tokens, real credentials, or private repository data.
+5. Keep external resources supplementary; the core lesson must remain understandable without hunting through tutorials.
+
+## Required local check
+
+Run:
+
+```bash
+python scripts/validate_repo.py
+```
+
+The same validator runs on both Linux and Windows in GitHub Actions.
+
+## Pull request standard
+
+A useful pull request should explain:
+
+- what learner problem it solves
+- what behavior or understanding changes
+- how the change was tested
+- any safety implications
+
+For changes that add or modify a Git command exercise, include the expected observable repository state before and after the exercise.
+
+## Course design rule
+
+The learning loop is:
+
+> **LEARN → PREDICT → DO → INSPECT → BREAK/RECOVER → EXPLAIN → PROVE**
+
+Not every lesson needs every stage as a heading, but major capabilities should eventually require evidence rather than passive reading.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adham Mahmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Module_0_Setup/Exercises/README.md

@@ -0,0 +1,26 @@
+# Module 0 Exercises — Setup and Mental Model
+
+Use your disposable `git-github-lab` repository. Do not perform these exercises in the course repository.
+
+## Challenge 1 — Prove your environment
+
+Without copying commands from the guide, prove that:
+
+- Git is installed and callable from your terminal
+- your Git identity is configured intentionally
+- you know which directory you are currently in
+- you can distinguish a normal folder from a Git repository
+
+**Evidence:** record the commands you chose and explain what each output proved.
+
+## Challenge 2 — Repository boundary
+
+Create one normal folder and one Git repository. Put a file in each. Predict what `git status` will do in both locations, then test your prediction.
+
+**Pass when:** you can explain what `.git` represents and why Git commands care about repository boundaries.
+
+## Challenge 3 — Rebuild from memory
+
+Delete only your disposable practice repository, recreate it from scratch, initialize Git, create a first file, inspect state, make the first commit, and show the history.
+
+**Do not advance** if you need a command-by-command recipe to complete this challenge.

Module_1_Daily_Core/Exercises/README.md

@@ -0,0 +1,41 @@
+# Module 1 Exercises — Daily Core
+
+Work only in your disposable student lab.
+
+## Challenge 1 — Three states of one file
+
+Create a file, stage it, then modify it again before committing.
+
+Before running any corrective command, predict what each of these will show:
+
+```bash
+git status
+git diff
+git diff --staged
+```
+
+Explain why the same file can appear in both staged and unstaged state.
+
+## Challenge 2 — Selective commit
+
+Create changes in at least three files. Make one focused commit that intentionally includes only part of the work.
+
+**Evidence:** show the staged diff before the commit and explain why the omitted changes did not belong in it.
+
+## Challenge 3 — Ignore-rule trap
+
+Track a harmless fake configuration file, then add its pattern to `.gitignore`.
+
+Predict whether Git stops tracking it. Test the prediction and explain why `.gitignore` is not a secret-removal mechanism.
+
+## Boss check — Inspect before acting
+
+Have another person or future-you make several mixed changes in the lab. Without immediately staging anything, determine:
+
+- what changed
+- what is staged
+- what is not staged
+- what is untracked
+- what belongs in the next commit
+
+**Pass when:** your first instinct is inspection, not `git add .`.

Module_2_Branching/Exercises/README.md

@@ -0,0 +1,33 @@
+# Module 2 Exercises — Branching
+
+Use the disposable student lab.
+
+## Challenge 1 — Predict branch movement
+
+Create two commits on `main`, create a feature branch, add two more commits there, and draw the commit graph you expect before inspecting it.
+
+Then run:
+
+```bash
+git log --oneline --graph --decorate --all
+```
+
+Explain what the branch names point to.
+
+## Challenge 2 — Fast-forward vs merge commit
+
+Produce one merge that can fast-forward and one merge where both branches have diverged.
+
+Before each merge, predict the resulting graph.
+
+**Pass when:** you can explain why the outcomes differ without describing branches as folders or copies.
+
+## Challenge 3 — Branch cleanup
+
+Merge a finished feature, verify the work is reachable from `main`, then delete the local feature branch.
+
+Explain why deleting the branch name does not delete commits that remain reachable from `main`.
+
+## Boss check — Unknown graph
+
+Create a small history with at least three branches and six commits. Leave it for a while, return without notes, inspect it, and explain which work is merged and which work remains isolated before running a merge command.

Module_3_Remotes/Exercises/README.md

@@ -0,0 +1,33 @@
+# Module 3 Exercises — Remotes
+
+Use your disposable student lab plus its GitHub remote.
+
+## Challenge 1 — Local vs remote truth
+
+Create a local commit without pushing it. Then inspect:
+
+```bash
+git status
+git log --oneline --decorate --graph --all
+git branch -vv
+```
+
+Explain what exists locally and what GitHub does not know yet.
+
+## Challenge 2 — Remote changes first
+
+Make a harmless change on GitHub, then return to your local clone.
+
+Do **not** immediately run `git pull`.
+
+First fetch and inspect the difference between your local branch and its remote-tracking branch. Decide how to integrate only after you understand the state.
+
+## Challenge 3 — Two clones
+
+Clone the same practice repository into two separate folders. Make a commit in clone A and push it. In clone B, inspect the stale state, fetch, explain what changed, then integrate deliberately.
+
+## Boss check — Divergence diagnosis
+
+Create one unpublished local commit and one different remote commit so the branch diverges. Before integrating anything, draw the graph and explain your available choices.
+
+**Pass when:** `fetch → inspect → decide` feels natural and `pull` is no longer a mystery command.

Module_4_Collaboration/Exercises/README.md

@@ -0,0 +1,33 @@
+# Module 4 Exercises — Collaboration
+
+Use your disposable lab or a repository where collaboration is welcome.
+
+## Challenge 1 — Issue to pull request
+
+Create an Issue describing a small, testable change. Create a branch from current `main`, implement only that scope, push it, and open a pull request that links the Issue.
+
+**Evidence:** the PR explains what changed, how it was checked, and what remains out of scope.
+
+## Challenge 2 — Review without rubber-stamping
+
+Inspect a harmless practice PR as if you were its reviewer. Record at least:
+
+- one question about intent or behavior,
+- one concrete improvement request,
+- the final decision you would make after the concern is resolved and why.
+
+If a real collaborator is available, perform the review on their PR. If you are studying solo, keep the review notes in your lab; GitHub does not allow you to approve your own PR, and this course does not require another person just to pass the exercise.
+
+Explain the difference between reviewing a change and merely confirming that a diff exists.
+
+## Challenge 3 — Update the same PR
+
+Respond to your review feedback by committing to the existing PR branch. Do not open a replacement PR.
+
+Explain why the pull request updates automatically.
+
+## Boss check — Fork and upstream
+
+Fork a practice repository, clone your fork, add the original repository as `upstream`, fetch from it, and show which refs belong to `origin` versus `upstream`.
+
+**Pass when:** you can describe the contributor workflow without confusing forks, branches, remotes, and pull requests.

Module_5_Fixing_Mistakes/Exercises/README.md

@@ -0,0 +1,30 @@
+# Module 5 Exercises — Fixing Mistakes and Recovery
+
+Use only your disposable student lab. Read [`../../SAFETY.md`](../../SAFETY.md) before destructive commands.
+
+## Challenge 1 — Choose the least destructive tool
+
+Create four separate mistakes:
+
+- staged the wrong file
+- changed a tracked file but want its last committed version back
+- committed the right change with the wrong message
+- committed something that should be undone after it has been shared
+
+For each case, state your intended final state **before** choosing a command.
+
+## Challenge 2 — Stash deliberately
+
+Create tracked work in progress, stash it, verify the working tree state, make an unrelated commit, then restore the stash and resolve any conflict if one appears.
+
+Explain what the stash protected and what it did not.
+
+## Challenge 3 — Recover a displaced commit
+
+Create a disposable commit, move the branch away from it, then recover it using reflog by creating a recovery branch at the correct commit.
+
+**Pass when:** you can prove the commit is reachable again and explain why reflog was useful.
+
+## Boss check — Shared-history decision
+
+Given a mistake already pushed to a branch another person may have pulled, explain why `revert` is usually safer than rewriting that history. Then demonstrate the safe repair in your practice repository.

Module_6_Real_World/Exercises/README.md

@@ -0,0 +1,33 @@
+# Module 6 Exercises — Real-World Git
+
+Use the disposable student lab. Read [`../../SAFETY.md`](../../SAFETY.md) before rewriting history.
+
+## Challenge 1 — Conflict from divergence
+
+Create a genuine same-line conflict by changing one committed line differently on two diverged branches. Before resolving it, explain:
+
+- what `HEAD` represents
+- what each conflict side contains
+- what final content you intend to keep
+
+Resolve, commit, and prove the working tree is clean.
+
+## Challenge 2 — Rebase boundary
+
+Rebase an unpublished feature branch onto updated `main`. Compare commit IDs before and after.
+
+Then explain why doing the same rewrite to a shared branch can disrupt collaborators.
+
+## Challenge 3 — Release evidence
+
+Create an annotated version tag in your lab, inspect it, push it, and create a GitHub Release with concise notes tied to actual changes.
+
+## Challenge 4 — Controlled CI lab
+
+Complete the self-contained exercise in [`../../examples/actions/README.md`](../../examples/actions/README.md). You must be able to explain the workflow trigger, job, steps, and why the intentionally failing test blocks the check.
+
+## Boss check — Disaster lab
+
+Combine at least three failures in one practice repository: a merge conflict, remote divergence, and a displaced commit recoverable through reflog. Diagnose before repairing.
+
+**Pass when:** you can narrate repository state first, choose the least destructive appropriate operation, and verify the final graph and working tree.