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

Ship real module challenges, self-contained Actions practice, cross-platform quality gates, repository hygiene checks, Git behavior smoke tests, safer history-rewrite guidance, contribution rules, and licensing.

Author: adhamcodes

.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/.gitkeep

@@ -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_0_Setup/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_1_Daily_Core/Exercises/.gitkeep

@@ -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.