From e96883af23626f455ecc046767e3d615d8ada83d Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 06:55:33 +0600 Subject: [PATCH 01/17] Redesign student workflow for course v2 --- START_HERE.md | 139 +++++++++++++++++++++----------------------------- 1 file changed, 58 insertions(+), 81 deletions(-) diff --git a/START_HERE.md b/START_HERE.md index 69263e7..c7d6939 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -1,115 +1,92 @@ -# START HERE πŸ‘‹ (Read This First) +# START HERE β€” Git & GitHub: Zero to Independent -Hi. This file explains how to use this whole repo in the simplest way possible. -If you only read ONE file, read this one. It's easy. Take your time. +This repository is the **course**. Your practice should happen in a separate throwaway learning repository so you can experiment, break things, recover them, and build real Git history without modifying the curriculum itself. ---- +## 1. What you are learning -## What is this repo? +- **Git** = version control on your computer. It records project history as commits. +- **GitHub** = a hosting and collaboration platform for Git repositories. -It's a **course that teaches you Git and GitHub** β€” the tools you use to save your code and share it with the world. +The goal is not memorizing commands. The goal is becoming able to inspect a repository, make changes safely, recover from mistakes, collaborate through branches and pull requests, and understand what Git is doing. -Think of it like a **cookbook with 28 recipes**. +## 2. Create your student lab first -- Each **recipe = 1 lesson**. -- You do **one lesson per sitting** (no clock, no rush). -- Every lesson teaches you ONE skill and asks you to TRY it yourself. -- When you can do it **without looking**, you move to the next lesson. -- After 28 lessons, Git stops being scary and becomes a tool you just... use. +Before Lesson 1, create a folder/repository named something like: ---- - -## First, what's the difference between Git and GitHub? - -Super simple: - -- **Git** = a "save button with superpowers" that lives on your computer. It remembers every version of your work. -- **GitHub** = a website where you put your Git projects online, so you can back them up and share them. - -You'll learn both. Module 0 explains this properly. - ---- - -## The 2 kinds of files you'll use +```text +git-github-lab/ +β”œβ”€β”€ notes/ +β”œβ”€β”€ experiments/ +└── README.md +``` -1. **The Guide** = the teacher. It tells you WHAT to learn in each lesson and the exact commands to type. - - Example: `Module_0_Setup/Module_0_Guide.md` +All practice, deliberate mistakes, lesson logs, branches, conflicts, resets, and recovery exercises happen there. -2. **The Lesson Log** = your worksheet. It has check-boxes so you can track what you've done. - - Example: `Module_0_Setup/Logs/Lesson_01.md` - - One is already made for every lesson. You don't create them. +**Do not use this course repository as your practice playground.** Treat this repo as read-only curriculum. -That's it. A teacher file and a worksheet file. +See **[STUDENT_LAB.md](STUDENT_LAB.md)** for the exact setup. ---- +## 3. How every lesson works -## Your Lesson, Step by Step +Each lesson uses this loop: -> You can read the guides on the GitHub **website**. You'll practice the commands in your **terminal** (the black text window) β€” the guides show you exactly what to type. +> **LEARN β†’ PREDICT β†’ DO β†’ INSPECT β†’ BREAK/RECOVER β†’ EXPLAIN β†’ TRANSITION CHECK** -**STEP 1 β€” Open the module guide.** -Start with `Module_0_Setup/Module_0_Guide.md`. Read Lesson 1. +A lesson is finished only when you can pass its Transition Condition without copying commands from the guide. -**STEP 2 β€” Open today's worksheet.** -In the same module, open the `Logs` folder and click the matching lesson (e.g. `Lesson_01.md`). +When a lesson contains a destructive command, first read **[SAFETY.md](SAFETY.md)**. -**STEP 3 β€” Do the 3 parts of the lesson:** -- 🟦 **LEARN** β€” read the short explanation in the guide. -- 🟩 **DO** β€” type the commands yourself in your terminal. Try them. Break them. See what happens. -- πŸŸ₯ **TRANSITION CONDITION** β€” a tiny test to prove you got it. +## 4. Course order -Tick the check-boxes in the log as you finish. +1. **Module 0 β€” Setup**: Git vs GitHub, installation, identity, first repository +2. **Module 1 β€” Daily Core**: status, diff, staging, commits, history, ignore rules +3. **Module 2 β€” Branching**: branches, switching, merging, branch inspection +4. **Module 3 β€” Remotes**: clone, push, fetch, pull, upstream tracking, divergence +5. **Module 4 β€” Collaboration**: forks, pull requests, review, issues, contribution etiquette +6. **Module 5 β€” Recovery**: restore, stash, amend, revert, reset, reflog +7. **Module 6 β€” Real World**: conflicts, rebase, tags/releases, Actions awareness +8. **Final Capstone**: complete a real contribution workflow and demonstrate recovery skills -**STEP 4 β€” The "Can I move on?" test.** -Each lesson ends with a **Transition Condition** β€” one small task, like *"Make a commit and see it in your history, with no guide open."* +## 5. What to do with the lesson logs -- If you CAN do it β†’ move to the next lesson. πŸŽ‰ -- If you CANNOT yet β†’ repeat the lesson. That's normal and smart. Do NOT skip ahead. +The `Logs/` files in this curriculum are templates/reference worksheets. Copy the relevant log into your own `git-github-lab/notes/` folder and fill it out there. ---- +Do not edit the public curriculum merely to tick boxes. -## Where do I practice? +## 6. The safety rule -Each module has an **`Exercises/`** folder. Use it as a safe playground β€” make test files, commit them, branch them, break things. Nothing here is precious. **Breaking things on purpose is how you learn Git.** +Before any command that can discard or rewrite work: ---- +```bash +git status +git diff +git log --oneline --decorate -10 +``` -## The "I'm scared I'll lose my work" promise +Then ask: -Read this and relax: **Git is almost impossible to permanently lose work in.** Once you've committed something, it's saved β€” even if you "delete" it, there are ways to bring it back. Module 5 ("Fixing Mistakes") teaches you exactly how to undo anything. By the end, you'll feel safe, not scared. +> **Is the work committed? Is it pushed/shared? Am I intentionally rewriting or deleting anything?** ---- +If you cannot answer those questions, stop and inspect before continuing. -## The map of the repo +## 7. The mastery rule -``` -git-github-course/ -β”œβ”€β”€ START_HERE.md <- this file -β”œβ”€β”€ README.md <- the big-picture course plan -β”œβ”€β”€ CHEATSHEET.md <- every command in one place (your quick reference) -β”œβ”€β”€ _Templates/ -β”‚ └── Lesson_Log.md <- a blank worksheet, in case you need a spare -β”œβ”€β”€ Module_0_Setup/ -β”‚ β”œβ”€β”€ Module_0_Guide.md <- teacher -β”‚ β”œβ”€β”€ Logs/ <- worksheets (Lesson_01 ...) -β”‚ └── Exercises/ <- your safe practice playground -β”œβ”€β”€ Module_1_Daily_Core/ <- same layout -β”œβ”€β”€ Module_2_Branching/ <- same layout -β”œβ”€β”€ Module_3_Remotes/ <- same layout -β”œβ”€β”€ Module_4_Collaboration/<- same layout -β”œβ”€β”€ Module_5_Fixing_Mistakes/ <- same layout -β”œβ”€β”€ Module_6_Real_World/ <- same layout -└── Capstone_First_Contribution/ <- your final project -``` +You are ready to move on when you can: -Every module looks the SAME. Learn one, you know them all. +- predict what a command will change, +- run it, +- inspect whether your prediction was correct, +- explain the result, +- recover if you deliberately create a failure. ---- +Finishing pages is not mastery. -## If you ever feel lost +## Start now -Say the loop out loud: +1. Open **[STUDENT_LAB.md](STUDENT_LAB.md)**. +2. Create your separate practice repo. +3. Then begin **[Module 0](Module_0_Setup/Module_0_Guide.md)**. -> **"Open the guide. Open the lesson log. Learn it. Do it in the terminal. Pass the little test."** +If you get lost later, return to this sentence: -That's the whole course. One lesson at a time. Now open `Module_0_Setup/Module_0_Guide.md` and start **Lesson 1**. +> **Read the lesson. Work in the lab. Inspect constantly. Pass the transition check from memory.** From 5d8b58c73947aabfaf75e7a4ef19062074db6032 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 06:55:46 +0600 Subject: [PATCH 02/17] Add isolated student lab workflow --- STUDENT_LAB.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 STUDENT_LAB.md diff --git a/STUDENT_LAB.md b/STUDENT_LAB.md new file mode 100644 index 0000000..9301a47 --- /dev/null +++ b/STUDENT_LAB.md @@ -0,0 +1,87 @@ +# Student Lab β€” Your Safe Git Playground + +The course repository is the textbook. This lab is where you actually use Git. + +## Create the lab + +Choose a normal development folder on your computer, then: + +```bash +mkdir git-github-lab +cd git-github-lab +git init +``` + +Create a simple README: + +```text +# Git & GitHub Lab + +Throwaway practice repository for learning Git safely. +``` + +Then make your first commit: + +```bash +git add README.md +git commit -m "Initialize Git learning lab" +``` + +## Recommended structure + +```text +git-github-lab/ +β”œβ”€β”€ README.md +β”œβ”€β”€ notes/ +β”œβ”€β”€ experiments/ +β”œβ”€β”€ conflict-lab/ +└── recovery-lab/ +``` + +You may delete, rename, branch, merge, reset, recover, and recreate files here. That is the point. + +## Why separate it from the course? + +A curriculum repository should stay stable. A Git-learning repository should become messy. + +Your lab gives you: + +- real commit history +- safe deliberate mistakes +- realistic branch practice +- conflict/recovery experiments +- something you can delete and recreate if necessary + +## Lesson workflow + +For every lesson: + +1. Read the lesson in the course repository. +2. Predict what each Git command will change. +3. Recreate the exercise in this lab. +4. Run `git status` before and after meaningful steps. +5. Use `git diff` or `git diff --staged` to inspect content changes. +6. Record errors/confusion in `notes/`. +7. Pass the Transition Condition without reading the commands. + +## Remote practice + +When Module 3 begins, create an empty GitHub repository named something like `git-github-lab` and connect this local repository to it. Do not use an important project for remote exercises. + +## Destructive-command boundary + +Use `recovery-lab/` for exercises involving reset, reflog, discarded edits, or rewritten history. Read **[SAFETY.md](SAFETY.md)** before those lessons. + +## Graduation condition + +By the end of the course, this lab should contain evidence that you have actually: + +- created meaningful commit history +- branched and merged +- resolved conflicts +- pushed/pulled/fetched +- recovered deliberately lost committed work +- practiced a safe revert +- inspected and understood divergence + +That history is more valuable than checked boxes in the curriculum repo. From 5de893c7f194d900672e8aaf2aeab13e5fcc73cd Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 06:55:57 +0600 Subject: [PATCH 03/17] Add Git safety and recovery rules --- SAFETY.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 SAFETY.md diff --git a/SAFETY.md b/SAFETY.md new file mode 100644 index 0000000..ce85809 --- /dev/null +++ b/SAFETY.md @@ -0,0 +1,75 @@ +# Git Safety Rules + +Git is powerful because it lets you rewrite or discard state. That also means some commands deserve a pause. + +## Before destructive or history-rewriting work + +Run: + +```bash +git status +git diff +git diff --staged +git log --oneline --decorate -10 +``` + +Ask: + +1. Is the work committed? +2. Is the commit already pushed/shared? +3. Am I trying to undo content, undo history, or merely unstage something? +4. Do I know which branch I am on? + +## Lower-risk recovery tools + +These usually preserve history or uncommitted work when used correctly: + +```bash +git restore --staged # unstage, keep working-tree edit +git stash # temporarily save tracked changes +git revert # make a new commit that undoes an old commit +git reflog # inspect recent HEAD/reference movements +``` + +These are not magic. Read the command output and inspect afterward. + +## Commands that can discard or rewrite work + +Pause before using: + +```bash +git restore +git reset --hard +git clean -fd +git push --force +``` + +`git restore ` can permanently discard uncommitted edits. `reset --hard` can overwrite both the index and working tree. `clean -fd` removes untracked files/directories. Force-pushing can rewrite shared remote history. + +## Safer recovery habit + +If you find a commit in `git reflog` that you want to preserve, prefer creating a recovery branch first: + +```bash +git switch -c recovery-branch +``` + +Now the commit has a named branch pointing to it while you inspect what happened. + +## Shared-history rule + +Rewriting your own unpublished commits can be useful. Rewriting commits other people may already depend on requires coordination. + +Do not use the simplistic rule "rebase is always dangerous." The real boundary is **shared history**. + +## The recovery mindset + +When something looks wrong: + +1. Stop typing commands. +2. Run `git status`. +3. Inspect the graph: `git log --oneline --graph --decorate --all`. +4. Check `git reflog` if a commit seems missing. +5. Create a recovery branch before experimenting further. + +Panic causes more damage than Git does. From 5c13beb79f9f0012372ee82b7b73acc9e89a3c28 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 06:56:19 +0600 Subject: [PATCH 04/17] Harden recovery lessons and safety boundaries --- Module_5_Fixing_Mistakes/Module_5_Guide.md | 186 +++++++++++++++------ 1 file changed, 138 insertions(+), 48 deletions(-) diff --git a/Module_5_Fixing_Mistakes/Module_5_Guide.md b/Module_5_Fixing_Mistakes/Module_5_Guide.md index e4a618b..315ca6b 100644 --- a/Module_5_Fixing_Mistakes/Module_5_Guide.md +++ b/Module_5_Fixing_Mistakes/Module_5_Guide.md @@ -1,104 +1,194 @@ -# MODULE 5 β€” Fixing Mistakes (Lessons 21-24) +# MODULE 5 β€” Fixing Mistakes (Lessons 21–24) -**Goal:** Kill the fear. Learn to undo almost anything in Git. After this module you'll feel safe experimenting, because you'll know how to get back. +**Goal:** Replace fear with a recovery process. You will learn the difference between changing files, changing the staging area, undoing commits, and rewriting history. **Resources:** -- Git book "Undoing Things": https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things -- GitHub blog β€” how to undo (concepts): https://github.blog/open-source/git/how-to-undo-almost-anything-with-git/ +- Git book β€” Undoing Things: https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things +- GitHub β€” Undoing changes: https://docs.github.com/en/get-started/using-git/undoing-changes -> 🟒 Safe anytime: `restore`, `stash`, `revert`, `reflog`, `reset --soft` -> πŸ”΄ Can delete work: `reset --hard`. Pause before using it. +> Before this module, read **[../SAFETY.md](../SAFETY.md)**. Do every destructive experiment only in your separate `git-github-lab` repository. --- -## Lesson 21 β€” Undo Before Committing: `restore` + `stash` +## Lesson 21 β€” Working-tree vs staging mistakes: `restore` and `stash` ### LEARN -- `git restore ` throws away unstaged edits to a file (back to last commit). -- `git restore --staged ` unstages a file but keeps your edits. -- `git stash` shelves your current changes so you have a clean slate; `git stash pop` brings them back. Great when you need to switch branches mid-edit. +There are two different questions: + +- **Do I want to keep the edit but remove it from the next commit?** Use `git restore --staged `. +- **Do I want to discard the uncommitted edit itself?** `git restore ` can do that β€” and the discarded edit may not be recoverable by Git because it was never committed. + +`git stash` temporarily stores tracked work so you can get a clean working tree. Treat it as temporary storage, not a long-term backup system. + +### PREDICT +Before each command below, say what you think will happen to: + +1. the working file, +2. the staging area, +3. commit history. ### DO ```bash -echo "oops" >> notes.txt -git restore notes.txt # change discarded -git status # clean +echo "important edit" >> notes.txt +git add notes.txt +git status + +git restore --staged notes.txt +git status +# The edit should remain in the file, but it is no longer staged. + +git stash +git status +git stash list +git stash pop +``` + +Now, only in a throwaway file: -echo "wip" >> notes.txt -git stash # changes shelved, working dir clean -git stash pop # changes return +```bash +echo "throwaway edit" > disposable.txt +git add disposable.txt +git commit -m "Add disposable file" +echo "uncommitted change" >> disposable.txt +git diff +git restore disposable.txt ``` +Inspect the file and explain what disappeared and why. + ### TRANSITION CONDITION -You can discard an unstaged change with `restore`, and shelve/restore work with `stash`. +Without the guide, demonstrate: +- unstage while keeping an edit, +- stash and restore tracked work, +- explain why `git restore ` can be destructive. --- -## Lesson 22 β€” Fix the Last Commit: `amend` + soft reset +## Lesson 22 β€” Fix your latest local commit: `amend` and soft reset ### LEARN -- `git commit --amend` rewrites your LAST commit β€” fix a typo in the message, or add a forgotten file. -- `git reset --soft HEAD~1` undoes the last commit but KEEPS the changes staged (as if you never committed). -- ⚠️ Only amend/rewrite commits you have NOT pushed/shared yet. +`git commit --amend` replaces your latest commit with a new commit. `git reset --soft HEAD~1` moves the branch back one commit while leaving that commit's changes staged. + +Both rewrite local history. They are useful for your own unpublished work. Once other people may depend on the commit, prefer preserving shared history instead of casually rewriting it. ### DO ```bash echo "line" >> notes.txt -git add . && git commit -m "Add lien" # oops, typo -git commit --amend -m "Add line" # fixed message +git add notes.txt +git commit -m "Add lien" -git reset --soft HEAD~1 # undo the commit, keep changes staged -git status # changes are staged again +git commit --amend -m "Add line" +git log --oneline -3 ``` +Then make another throwaway commit and inspect a soft reset: + +```bash +echo "another line" >> notes.txt +git add notes.txt +git commit -m "Add another line" +git reset --soft HEAD~1 +git status +git diff --staged +``` + +Recommit the staged change when finished. + ### TRANSITION CONDITION -You can fix a bad commit message with `--amend` and undo a commit (keeping the work) with `reset --soft`. +Explain why amend/reset change commit identity, demonstrate each on unpublished work, and show the resulting state with `git status`/`git log`. --- -## Lesson 23 β€” `revert` vs `reset` (Safe vs Sharp) +## Lesson 23 β€” Preserve history with `revert`; understand `reset` ### LEARN -- `git revert ` creates a NEW commit that undoes an old one. **Safe** β€” history is preserved. Use this for commits you've already pushed. -- `git reset` moves your branch pointer back. `--soft` keeps changes, `--hard` **deletes** them. Powerful but sharp. +`git revert ` creates a new commit whose patch reverses an earlier commit. That makes it a strong default for undoing a change that has already been shared. + +`git reset` moves a branch reference. Modes such as `--soft` and `--hard` additionally control what happens to the staging area and working tree. `--hard` can discard uncommitted work. ### DO +Create a harmless commit specifically for this exercise: + ```bash -git log --oneline # pick a commit hash to undo -git revert # makes a new "undo" commit (safe) +echo "temporary feature" > temp-feature.txt +git add temp-feature.txt +git commit -m "Add temporary feature" +git log --oneline -3 +``` + +Then revert that commit: -# Compare (in a throwaway test): -git reset --soft HEAD~1 # undo commit, keep work -# git reset --hard HEAD~1 # undo commit AND delete work β€” careful +```bash +git revert HEAD +git log --oneline -4 ``` +Observe that history contains both the original change and the later undo commit. + +For reset, use only a disposable branch/repository and inspect state before and after rather than memorizing flags. + ### TRANSITION CONDITION -You can explain when to use `revert` (shared/pushed) vs `reset` (local), and you've used `revert` to undo a commit. +You can explain: +- why revert is suitable for shared history, +- why reset rewrites where a branch points, +- why `reset --hard` requires extra care. --- -## Lesson 24 β€” Recover Lost Work: `reflog` +## Lesson 24 β€” Recover committed work with `reflog` ### LEARN -`git reflog` is your time machine. It logs every place `HEAD` has been β€” even commits you "lost" via a hard reset. As long as you committed at some point, you can almost always get it back. +`git reflog` records recent movements of references such as `HEAD` in your local repository. It can often help you find a commit after a reset, rebase, or accidental branch movement. + +It is **not** a universal backup for every lost file. Work that was never committed may not be recoverable from reflog. + +### DO β€” controlled recovery drill + +1. Make and commit a unique file: -### DO ```bash -git reflog # see your full history of moves -# find the hash from before your mistake, then: -git checkout # look at that state -# or to bring a lost commit back to a branch: -git reset --hard # (only when you're sure) +echo "recover me" > recovery.txt +git add recovery.txt +git commit -m "Add recovery target" +git log --oneline -3 +``` + +2. Record the commit hash somewhere outside the repo for the exercise. +3. In this throwaway lab only, move the branch back: + +```bash +git reset --hard HEAD~1 +``` + +4. Find the commit again: + +```bash +git reflog +``` + +5. **Preserve it safely by creating a branch instead of immediately hard-resetting again:** + +```bash +git switch -c recovered-work +``` + +6. Confirm `recovery.txt` is back and inspect the graph: + +```bash +git log --oneline --graph --decorate --all ``` ### TRANSITION CONDITION -**The fear-killer:** intentionally "lose" a commit with `reset --hard`, then recover it using `reflog`. Once you do this, Git stops being scary. +From memory, recover a deliberately displaced **committed** change using reflog and a recovery branch, and explain why an uncommitted edit is a different situation. --- ## Module 5 Complete When... -- [ ] You can undo uncommitted changes (restore, stash) -- [ ] You can fix/undo your last commit (amend, reset --soft) -- [ ] You know when to use revert vs reset -- [ ] You can recover lost work with reflog + +- [ ] You distinguish working-tree, staging, and history recovery +- [ ] You can unstage without discarding work +- [ ] You can stash and restore temporary work +- [ ] You can amend/reset your own unpublished history deliberately +- [ ] You can use revert to preserve shared history +- [ ] You can recover a displaced commit with reflog + a recovery branch - [ ] **All Transition Conditions passed β†’ start Module 6** From 3a7293d39e439db51ca50669370c2a2de1ee3e69 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 06:56:40 +0600 Subject: [PATCH 05/17] Fix conflict lab and modernize real-world Git lessons --- Module_6_Real_World/Module_6_Guide.md | 190 ++++++++++++++++++++------ 1 file changed, 145 insertions(+), 45 deletions(-) diff --git a/Module_6_Real_World/Module_6_Guide.md b/Module_6_Real_World/Module_6_Guide.md index a52d7bf..c000f80 100644 --- a/Module_6_Real_World/Module_6_Guide.md +++ b/Module_6_Real_World/Module_6_Guide.md @@ -1,108 +1,208 @@ -# MODULE 6 β€” Real-World Git (Lessons 25-28) +# MODULE 6 β€” Real-World Git (Lessons 25–28) -**Goal:** Handle the situations that scare beginners in real projects β€” merge conflicts, rebasing, releases β€” plus polish your GitHub presence. +**Goal:** Handle the situations that make beginners hesitate in real projects: conflicts, diverged history, rebasing, releases, and automation awareness. **Resources:** -- Git book "Basic Merge Conflicts": https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging -- Git book "Rebasing": https://git-scm.com/book/en/v2/Git-Branching-Rebasing -- GitHub Docs β€” managing releases: https://docs.github.com/en/repositories/releasing-projects-on-github -- GitHub Docs β€” profile README: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile +- Git book β€” Basic Merge Conflicts: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging +- Git book β€” Rebasing: https://git-scm.com/book/en/v2/Git-Branching-Rebasing +- GitHub Docs β€” Releases: https://docs.github.com/en/repositories/releasing-projects-on-github +- GitHub Docs β€” Actions: https://docs.github.com/en/actions --- -## Lesson 25 β€” Merge Conflicts (and How to Stay Calm) +## Lesson 25 β€” Merge conflicts: create one correctly, then resolve it calmly ### LEARN -A **conflict** happens when two branches change the SAME lines and Git can't decide which to keep. It's normal, not an error. Git marks the spot; you choose what stays. +A conflict happens when Git cannot automatically combine competing changes. A common case is when two branches change the same lines after they have diverged. + +A conflict is not corruption. Git stops and asks you to choose the final content. + +### DO β€” create a real conflict on purpose + +Start from `main` with a committed baseline: -### DO -1. Create a conflict on purpose: ```bash git switch main echo "Color: blue" > color.txt -git add . && git commit -m "Set color blue" +git add color.txt +git commit -m "Add baseline color" +``` +Create a feature branch and change the same line: + +```bash git switch -c change-color echo "Color: red" > color.txt -git add . && git commit -m "Set color red" +git add color.txt +git commit -m "Change color to red" +``` +Now **make main diverge** by changing that same line differently: + +```bash git switch main -git merge change-color # CONFLICT! +echo "Color: green" > color.txt +git add color.txt +git commit -m "Change color to green" ``` -2. Open `color.txt`. You'll see conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`). -3. Delete the marker lines, keep the line you want, then: + +Now merge: + +```bash +git merge change-color +``` + +Git should stop with a conflict because both branches changed the same line differently. + +Inspect: + +```bash +git status +``` + +Open `color.txt`. You will see conflict markers like: + +```text +<<<<<<< HEAD +Color: green +======= +Color: red +>>>>>>> change-color +``` + +Edit the file into the final content you actually want, remove the markers, then: + ```bash git add color.txt -git commit # completes the merge +git status +git commit -m "Resolve color conflict" +``` + +Inspect the result: + +```bash +git log --oneline --graph --decorate --all ``` ### TRANSITION CONDITION -**The big fear-killer:** create a merge conflict on purpose and resolve it cleanly, with no guide open. +Without the guide, deliberately create two diverging edits to the same line, trigger a conflict, explain the markers, resolve it, and verify a clean working tree. --- -## Lesson 26 β€” Rebase Basics (+ the Golden Rule) +## Lesson 26 β€” Rebase basics and the real shared-history rule ### LEARN -`git rebase` replays your branch's commits on top of another branch, giving a cleaner, linear history than a merge. Powerful but has one rule: -- πŸ”΄ **GOLDEN RULE:** never rebase commits you've already pushed/shared. It rewrites history and confuses everyone. +Rebase takes a series of commits and replays them onto a new base. That can make a feature branch easier to review and produce a linear history. + +Rebase creates new commit identities for the replayed commits. Therefore the important rule is not simply "never rebase anything pushed." The real rule is: + +> **Do not rewrite history that other people may already depend on unless the workflow explicitly expects it and you coordinate the rewrite.** + +Rebasing your own feature/PR branch is common in many teams. Rebasing a shared stable branch is a very different risk. ### DO +Create divergence: + ```bash -git switch -c feature -echo "feature work" > f.txt -git add . && git commit -m "Feature work" +git switch main +git switch -c feature-rebase +echo "feature" > feature.txt +git add feature.txt +git commit -m "Add feature work" git switch main -echo "main update" > m.txt -git add . && git commit -m "Main moved on" +echo "main update" > main-update.txt +git add main-update.txt +git commit -m "Add main update" +``` -git switch feature -git rebase main # replay feature's commits on top of updated main -git log --oneline --graph --all +Inspect first: + +```bash +git log --oneline --graph --decorate --all ``` +Then replay the feature branch on top of current `main`: + +```bash +git switch feature-rebase +git rebase main +git log --oneline --graph --decorate --all +``` + +Notice that the feature commit now has a different commit hash. + ### TRANSITION CONDITION -You can rebase a local branch onto `main` and state the golden rule of rebasing. +You can explain what rebase changes, identify when rewriting history is safe vs risky, and rebase your own disposable feature branch onto `main`. --- -## Lesson 27 β€” Tags & Releases +## Lesson 27 β€” Tags, versions, and GitHub Releases ### LEARN -A **tag** marks a specific commit as a version (e.g. `v1.0.0`). On GitHub, a tag can become a **Release** with notes and downloadable files β€” how projects ship versions. +A Git tag gives a stable name to a particular commit. Version tags such as `v1.0.0` are commonly used to mark releases. + +A GitHub Release is a GitHub object built around a tag, usually with release notes and optional downloadable artifacts. ### DO +Check the commit you intend to tag: + +```bash +git status +git log --oneline -5 +``` + +Create an annotated tag: + ```bash git tag -a v1.0.0 -m "First release" -git tag # list tags -git push origin v1.0.0 # push the tag to GitHub +git show v1.0.0 +git push origin v1.0.0 ``` -Then on GitHub: **Releases** β†’ **Draft a new release** β†’ pick your tag β†’ write notes β†’ publish. + +On GitHub, create a Release from that tag and write brief release notes describing what changed. ### TRANSITION CONDITION -You can create an annotated tag, push it, and turn it into a GitHub Release. +You can explain commit vs tag vs GitHub Release, create an annotated tag, inspect it, push it, and create release notes. --- -## Lesson 28 β€” Profile README + GitHub Actions Intro +## Lesson 28 β€” GitHub Actions awareness + professional repository signals ### LEARN -- A **profile README** is a special repo named exactly like your username (`adhamcodes/adhamcodes`) β€” its README shows on your GitHub profile page. Great first impression. -- **GitHub Actions** automate tasks (run tests, deploy) when you push. You don't need to master it now β€” just understand it exists and recognize a workflow file. +GitHub Actions runs automated workflows in response to repository events. Common uses include tests, linting, packaging, and deployment. + +A workflow normally lives under: + +```text +.github/workflows/*.yml +``` + +At this stage you do not need to become a CI engineer. You need to be able to open a workflow and identify: + +- what triggers it (`on`) +- its jobs (`jobs`) +- the steps each job performs (`steps`) +- whether a failed check should stop a merge + +A professional GitHub profile is useful too, but profile cosmetics are not evidence of engineering ability. Strong repositories, clear READMEs, useful commits, and real contributions matter more. ### DO -1. Create a repo named exactly your username. Add a `README.md` introducing yourself. Watch it appear on your profile. -2. Look at a `.github/workflows/*.yml` file in any popular repo to see what an automated workflow looks like. Read the top-level keys (`on`, `jobs`, `steps`). +1. Open a workflow from one of your own or a reputable public repository. +2. Identify the trigger, jobs, and major steps. +3. Find a commit or pull request with automated checks and inspect what passed/failed. +4. If you want a profile README, create a public repo named exactly your username and add a truthful README. Do not claim technologies you have not actually used. ### TRANSITION CONDITION -You have a profile README live on your GitHub profile, and you can explain in one sentence what GitHub Actions does. +You can explain what CI/Actions does, locate a workflow, identify its trigger/jobs/steps, and explain why a green check is useful but does not prove software correctness by itself. --- ## Module 6 Complete When... -- [ ] You can resolve a merge conflict calmly -- [ ] You can rebase and you know the golden rule -- [ ] You can tag a version and publish a Release -- [ ] You have a profile README and understand Actions at a high level + +- [ ] You can deliberately create and resolve a real merge conflict +- [ ] You understand divergence rather than treating conflicts as random errors +- [ ] You can rebase your own branch and explain the shared-history boundary +- [ ] You can tag and release a version deliberately +- [ ] You can read a basic GitHub Actions workflow - [ ] **All Transition Conditions passed β†’ start the Capstone** From 45b6b73db1250d3a2ab892c826d5d2f0c2b3a282 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 06:56:57 +0600 Subject: [PATCH 06/17] Add cumulative mastery assessments --- ASSESSMENTS.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 ASSESSMENTS.md diff --git a/ASSESSMENTS.md b/ASSESSMENTS.md new file mode 100644 index 0000000..639e565 --- /dev/null +++ b/ASSESSMENTS.md @@ -0,0 +1,106 @@ +# Cumulative Mastery Assessments + +These checks are intentionally cumulative. Do them in your separate `git-github-lab` repository. + +Do not read the command solutions while attempting them. Use `git status`, `git diff`, `git log`, `git help`, and official documentation as needed. + +## Gate A β€” Local Git Ready (after Module 1) + +Without copying commands: + +1. Create a repository. +2. Make two files. +3. Commit only one of them. +4. Explain why the other file was excluded. +5. Modify the committed file. +6. Show the unstaged diff. +7. Stage it. +8. Show the staged diff. +9. Commit it with a useful message. +10. Add an ignore rule and prove it works. + +Pass when you can explain the working tree, staging area, and commit history while demonstrating them. + +## Gate B β€” Branching Ready (after Module 2) + +1. Start with a clean `main`. +2. Create two feature branches from the same baseline. +3. Make different commits on both. +4. Inspect the graph. +5. Merge one branch. +6. Predict whether the second merge will fast-forward, auto-merge, or conflict. +7. Perform it and explain the result. +8. Clean up merged branches safely. + +## Gate C β€” GitHub Round Trip (after Module 3) + +Using a disposable GitHub repository: + +1. Clone it on your computer. +2. Make and push a local commit. +3. Make a different commit through GitHub's web editor. +4. Use `fetch` first and inspect the relationship before updating your local branch. +5. Bring the remote change down. +6. Push another local change. +7. Explain `origin`, upstream tracking, fetch, pull, and push. + +## Gate D β€” Collaboration Ready (after Module 4) + +In a practice repository or with a study partner: + +1. Open an Issue describing a small change. +2. Create a branch for it. +3. Make focused commits. +4. Push the branch. +5. Open a Pull Request linked to the Issue. +6. Read the diff as a reviewer would. +7. Receive or simulate review feedback. +8. Update the same PR with another commit. +9. Merge it and confirm the Issue closes. + +## Gate E β€” Recovery Ready (after Module 5) + +You must demonstrate all of these without damaging important work: + +- unstage while preserving edits +- stash and restore work +- revert a committed change +- amend an unpublished commit +- use a soft reset and explain the resulting staged state +- deliberately displace a committed change and recover it through reflog + a recovery branch + +Before each potentially destructive action, state what you expect to happen. + +## Final Disaster Lab (after Module 6) + +Create a throwaway repository containing several meaningful commits and branches. Then intentionally create this situation: + +1. feature branch and `main` diverge +2. same line changes on both branches +3. merge conflict occurs +4. one local commit becomes "lost" through a deliberate reset +5. remote has a commit local does not yet have + +Recover the repository into a clean, understandable state. + +Required evidence: + +```bash +git status +git log --oneline --graph --decorate --all +git reflog +``` + +At the end, write a short incident report: + +- what happened +- what Git state you observed +- which recovery actions you chose +- why those actions were safer than alternatives +- what you would do differently in an important repository + +## Graduation standard + +You are not finished because you remember every flag. + +You are finished when an unfamiliar Git problem causes you to **inspect first**, form a mental model of the repository state, choose a deliberate operation, and verify the result afterward. From bd2acd44fde99115dc8c682a7d2a34693dafdac2 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 06:57:14 +0600 Subject: [PATCH 07/17] Reframe course v2 around independence and recovery --- README.md | 123 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 77 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index a4c64ee..0e47b59 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,100 @@ -# Git & GitHub: Zero to Confident +# Git & GitHub: Zero to Independent -> A hands-on, do-it-yourself course that takes you from "what even is Git?" to confidently branching, collaborating, fixing mistakes, and contributing to open source. +> A hands-on mini-academy for learning Git by using it, breaking it, inspecting it, recovering it, and collaborating with it. -> 🟒 **New here? Read [`START_HERE.md`](./START_HERE.md) first** β€” it explains exactly how to use this repo. +**Start here:** [`START_HERE.md`](START_HERE.md) ---- +This course is designed for beginners who want more than a list of commands. The target is a learner who can look at an unfamiliar repository state, understand what Git is telling them, make a deliberate change, and recover when something goes wrong. -## Who This Is For +## Learning loop -Beginners who can use a computer but freeze up at the command line. If you've ever been scared of "breaking something" in Git, this course is built for you. By the end, Git is a tool you *use*, not a thing you *fear*. +> **LEARN β†’ PREDICT β†’ DO β†’ INSPECT β†’ BREAK/RECOVER β†’ EXPLAIN β†’ PROVE** -## How It Works +Every module ends in evidence, not just reading. -This is the same proven format as a daily-roadmap course, but **lesson-based** instead of timed: +## Course map -- The course is split into **7 modules** (Setup β†’ Real-World) plus a **Capstone**. -- Each module has a **Guide** with numbered **lessons**. -- Every lesson follows the same shape: **LEARN β†’ DO (hands-on) β†’ TRANSITION CONDITION**. -- You do **not** advance until you can pass the Transition Condition **without looking it up**. -- There are pre-made **log files** to track each lesson, and an **Exercises** folder to practice in. +| Module | Capability | +|---|---| +| **0 β€” Setup** | distinguish Git/GitHub, configure Git, create repositories safely | +| **1 β€” Daily Core** | status, diff, staging, commits, history, ignore rules | +| **2 β€” Branching** | isolate work, inspect branches, merge deliberately | +| **3 β€” Remotes** | clone, push, fetch, pull, tracking, remote/local relationships | +| **4 β€” Collaboration** | forks, PRs, reviews, Issues, contribution etiquette | +| **5 β€” Recovery** | restore, stash, amend, revert, reset, reflog, recovery branches | +| **6 β€” Real World** | conflicts, divergence, rebase boundaries, tags/releases, CI awareness | +| **Capstone** | complete a real contribution workflow and demonstrate recovery skills | -> Do these alongside your main work β€” about one lesson per sitting. No rush. Muscle memory beats speed. +The original course contains 28 lessons. v2 keeps the accessible lesson-based structure while strengthening technical accuracy, safety, cumulative assessment, and professional workflow. ---- +## Important: use a separate practice repository -## The Course Map +Treat this repo as the textbook. Practice in your own disposable **`git-github-lab`** repository. -| Module | You'll master | -|---|---| -| **0 β€” Setup** | Git vs GitHub, install, `config`, authentication, your first repo | -| **1 β€” Daily Core Loop** | `status`, `add`, `commit`, `log`, `.gitignore`, great commit messages | -| **2 β€” Branching & Merging** | branches, switching, merging, fast-forward vs merge commits | -| **3 β€” Remotes** | `clone`, `push`, `pull`, `fetch`, upstream tracking | -| **4 β€” Collaboration** | forks, Pull Requests, code review, Issues, PR etiquette | -| **5 β€” Fixing Mistakes** | `restore`, `stash`, `amend`, `revert`, `reset`, `reflog` (your safety net) | -| **6 β€” Real-World** | merge conflicts, rebase basics, tags & releases, profile README, GitHub Actions intro | -| **Capstone** | Your first real open-source contribution + a polished GitHub profile | +That separation lets you create conflicts, reset history, recover commits, and make a mess without modifying the curriculum. + +Setup: **[`STUDENT_LAB.md`](STUDENT_LAB.md)** + +Safety rules: **[`SAFETY.md`](SAFETY.md)** + +Cumulative gates: **[`ASSESSMENTS.md`](ASSESSMENTS.md)** + +## Mastery gates + +The course is not timed. Move forward when you can demonstrate the capability from memory and explain the state changes you caused. + +Major cumulative gates cover: + +- local Git fundamentals +- branching +- remote/GitHub round trips +- collaboration +- recovery +- a final Git disaster/recovery lab + +See **[`ASSESSMENTS.md`](ASSESSMENTS.md)**. -**28 lessons total.** +## What you should be able to do when finished ---- +You should be able to: -## Progress Dashboard +- explain Git's working tree, staging area, commits, branches, and remotes +- inspect before acting instead of guessing +- create focused commits and useful history +- branch/merge and resolve conflicts +- clone/fetch/pull/push deliberately +- open and review pull requests +- distinguish safe history-preserving recovery from history rewriting +- use reflog to recover displaced committed work +- understand the shared-history boundary for rebase/reset/force operations +- tag a version and understand GitHub Releases +- read a basic GitHub Actions workflow +- make a small, respectful open-source contribution -- [ ] Module 0 β€” Setup -- [ ] Module 1 β€” Daily Core Loop -- [ ] Module 2 β€” Branching & Merging -- [ ] Module 3 β€” Remotes -- [ ] Module 4 β€” Collaboration -- [ ] Module 5 β€” Fixing Mistakes -- [ ] Module 6 β€” Real-World -- [ ] Capstone β€” First Contribution + Profile +## Core commands are not the course -Check a box only when you've passed every Transition Condition in that module. +You will use these constantly: ---- +```bash +git status +git diff +git add +git commit +git log +git switch +git fetch +git pull +git push +``` -## The One Hard Rule +But competence comes from knowing **what state they change and why**, not from memorizing syntax. -Every lesson has a **Transition Condition** β€” a small task you must do from memory, no guide open (e.g. *"Resolve a merge conflict on purpose"*). If you can't, repeat the lesson. **Understanding beats finishing.** +## Reference ---- +- [`CHEATSHEET.md`](CHEATSHEET.md) β€” quick command reference +- [Pro Git](https://git-scm.com/book/en/v2) β€” free official Git book +- [GitHub Docs](https://docs.github.com/en/get-started) β€” GitHub workflows and product documentation -## Quick Links +## Begin -- πŸ“– [START_HERE.md](./START_HERE.md) β€” how to use this repo (super simple) -- 🧾 [CHEATSHEET.md](./CHEATSHEET.md) β€” every command in one place -- 🧱 [Module 0 β€” Setup](./Module_0_Setup/Module_0_Guide.md) β€” begin here +Open **[`START_HERE.md`](START_HERE.md)** and create your student lab before Lesson 1. From 330d4877ce203cc92d538db664c4470273ec840a Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:09:00 +0600 Subject: [PATCH 08/17] Strengthen setup and Git mental models --- Module_0_Setup/Module_0_Guide.md | 173 ++++++++++++++++++++++++------- 1 file changed, 135 insertions(+), 38 deletions(-) diff --git a/Module_0_Setup/Module_0_Guide.md b/Module_0_Setup/Module_0_Guide.md index fbd6825..33963a4 100644 --- a/Module_0_Setup/Module_0_Guide.md +++ b/Module_0_Setup/Module_0_Guide.md @@ -1,83 +1,180 @@ -# MODULE 0 β€” Setup (Lessons 1-3) +# MODULE 0 β€” Setup (Lessons 1–3) -**Goal:** Understand what Git and GitHub actually are, get Git working on your computer, and connect it to GitHub. +**Goal:** Understand what Git and GitHub actually are, install/configure Git safely, and create the disposable student lab used throughout this course. -**Resources:** -- Official Git book (free): https://git-scm.com/book/en/v2 -- GitHub Docs β€” Get started: https://docs.github.com/en/get-started -- Download Git: https://git-scm.com/downloads +**Primary references:** +- [Pro Git β€” Getting Started](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) +- [GitHub Docs β€” Get started](https://docs.github.com/en/get-started) +- [Download Git](https://git-scm.com/downloads) + +> Before Lesson 1, read [`../../STUDENT_LAB.md`](../STUDENT_LAB.md) if you have not already. This curriculum repo is the textbook; your separate `git-github-lab` repo is where you experiment. --- -## Lesson 1 β€” Git vs GitHub + Install +## Lesson 1 β€” Git, GitHub, repositories, and installation ### LEARN -- **Git** is a program on YOUR computer that records snapshots ("commits") of your files over time. It works offline. -- **GitHub** is a website that stores Git repositories online so you can back them up and share/collaborate. -- Analogy: Git is the "save with full history" tool; GitHub is the cloud where you park and share those saves. + +**Git** is a distributed version-control system. It records versions of a project as commits and lets you inspect, compare, branch, combine, and recover those versions locally. + +**GitHub** is a hosting/collaboration platform built around Git repositories. It adds remote hosting, Pull Requests, Issues, code review, Actions, Releases, permissions, and social/project features. + +A **repository** is a project whose Git metadata and history live in a hidden `.git` directory at its root. Git does not magically upload or back up every edit you make. You deliberately select changes and create commits. + +A useful first mental model: + +```text +files on your computer + ↓ + Git +(local history and branches) + ↓ push / ↑ fetch + GitHub +(remote copy + collaboration) +``` + +Git can work without GitHub. GitHub can host Git repositories created with Git. ### DO -1. Install Git from https://git-scm.com/downloads (pick your operating system). -2. Open your terminal (Windows: "Git Bash"; Mac: "Terminal"; Linux: your terminal). -3. Check it worked: + +Install Git from , then open a terminal and run: + ```bash git --version ``` -You should see a version number like `git version 2.x.x`. + +You should see a Git version. + +Then answer without looking: + +1. Could you commit while offline? +2. Does editing a file automatically create a commit? +3. Is GitHub the same program as Git? + +Expected ideas: **yes, no, no**. + +### INSPECT + +Run: + +```bash +git help -a +``` + +You do not need to understand the list. The point is to notice that Git is a command-line program with many operations; this course will teach the small subset you need first. ### TRANSITION CONDITION -You can explain, in one sentence each, what Git is and what GitHub is β€” and `git --version` prints a version on your machine. + +Without the guide open, explain Git, GitHub, commit, and repository in your own words, and show that `git --version` works. --- -## Lesson 2 β€” Configure Git +## Lesson 2 β€” Identity, configuration, and privacy ### LEARN -Git stamps your name and email on every commit. You set this once. This is not a login β€” it's just a label on your snapshots. + +Every commit records an author name and email. These are **commit metadata**, not your GitHub password and not necessarily your login email. + +Git has configuration at several scopes. In this course you will mostly use: + +- `--global` β€” your user-level defaults +- `--local` β€” settings for only the current repository + +GitHub can associate commits with your account when the commit email matches a verified account email. If you do not want your personal email exposed in public commit history, GitHub provides a `noreply` address in account email settings. ### DO + +Set your identity deliberately: + ```bash git config --global user.name "Your Name" -git config --global user.email "you@example.com" # use the email on your GitHub account +git config --global user.email "your-chosen-commit-email@example.com" git config --global init.defaultBranch main -git config --list # check your settings (press q to quit) ``` +Inspect the values and where they came from: + +```bash +git config --global --list +git config --show-origin --get user.name +git config --show-origin --get user.email +``` + +Optional: if you want a different identity in one repository later, use `git config user.name ...` and `git config user.email ...` **without** `--global` while inside that repo. + ### TRANSITION CONDITION -`git config --list` shows your name, email, and `init.defaultBranch=main`. + +You can explain the difference between global and local Git configuration, and you can show your configured name, email, and default branch. --- -## Lesson 3 β€” Your First Repo + Connect to GitHub +## Lesson 3 β€” Create the student lab and understand `.git` ### LEARN -- A "repository" (repo) is just a folder that Git is watching. -- `git init` starts watching a folder. -- To connect to GitHub you need to **authenticate**. The easiest beginner-friendly way is the **GitHub CLI** (`gh`) or signing in when prompted. (SSH keys are an alternative you can learn later.) + +`git init` creates a new repository by adding a hidden `.git` directory. That directory contains Git's local metadata, refs, object database, and configuration. + +Your working files remain ordinary files. Git begins with **no commits**. You will decide what becomes history in Module 1. + +For this course, use a disposable practice repository rather than modifying the curriculum repository. ### DO -1. Make a practice folder and turn it into a repo: + +Create your lab in a convenient location: + ```bash -mkdir git-practice -cd git-practice +mkdir git-github-lab +cd git-github-lab git init +git status ``` -You'll see: *Initialized empty Git repository*. A hidden `.git` folder now exists β€” that's Git's brain. Don't touch it. -2. Create a free account at https://github.com if you don't have one. -3. (Recommended) Install the GitHub CLI from https://cli.github.com and run: +You should see that you are on `main` with no commits yet. + +Create a tiny marker file: + ```bash -gh auth login +echo "Git/GitHub student lab" > README.md +git status ``` -Follow the prompts (choose GitHub.com β†’ HTTPS β†’ login with browser). This sets up authentication so pushing later "just works." + +Notice that Git reports the file as **untracked**. Do not commit it yet; Module 1 starts there. + +### GitHub authentication β€” prepare, do not overcomplicate it + +You need a GitHub account before the remote modules. You **do not** need to memorize authentication internals now. + +For HTTPS on modern Git for Windows/macOS, Git Credential Manager can normally open a browser sign-in when Git first needs credentials. GitHub CLI (`gh auth login`) and SSH keys are valid alternatives, but neither is required for understanding local Git. + +If you already have working GitHub authentication, leave it alone. + +### INSPECT + +Run: + +```bash +git status +git rev-parse --show-toplevel +git config --local --list +``` + +The first tells you repository state. The second tells you the repository root. The third shows repository-specific configuration. ### TRANSITION CONDITION -You can create a new folder, run `git init`, and confirm it's a repo (`git status` works inside it without error). You have a GitHub account and have logged in (via `gh auth login` or a browser sign-in). + +From memory, create a new disposable folder, initialize it with Git, create an untracked file, and use `git status` to explain the state. You can also state what the `.git` directory is for. --- -## Module 0 Complete When... -- [ ] Git is installed and configured with your name/email -- [ ] You can create a repo with `git init` -- [ ] You have a GitHub account and are authenticated -- [ ] **All Transition Conditions above passed β†’ start Module 1** +## Module 0 gate + +You are ready for Module 1 when you can: + +- [ ] distinguish Git from GitHub +- [ ] explain what a repository and commit are at a high level +- [ ] show Git is installed +- [ ] identify your configured commit identity +- [ ] create and inspect a repository with `git init` and `git status` +- [ ] keep course content separate from your disposable student lab + +Then continue to **Module 1 β€” Daily Core**. \ No newline at end of file From 4b57a63563d2613b9f11a01d36f36c9209dc2cef Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:09:33 +0600 Subject: [PATCH 09/17] Upgrade daily Git workflow and staging discipline --- Module_1_Daily_Core/Module_1_Guide.md | 316 ++++++++++++++++++++------ 1 file changed, 247 insertions(+), 69 deletions(-) diff --git a/Module_1_Daily_Core/Module_1_Guide.md b/Module_1_Daily_Core/Module_1_Guide.md index 66c5b27..377b71e 100644 --- a/Module_1_Daily_Core/Module_1_Guide.md +++ b/Module_1_Daily_Core/Module_1_Guide.md @@ -1,132 +1,310 @@ -# MODULE 1 β€” The Daily Core Loop (Lessons 4-8) +# MODULE 1 β€” The Daily Core Loop (Lessons 4–8) -**Goal:** Master the everyday Git cycle you'll use thousands of times: see what changed, stage it, commit it, review history. This is 90% of daily Git. +**Goal:** Learn the everyday Git loop by understanding repository state, reviewing changes before staging, creating focused commits, and reading history deliberately. -**Resources:** -- Git book Ch.2 "Git Basics": https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository -- GitHub Docs β€” committing: https://docs.github.com/en/get-started/using-git +**Primary references:** +- [Pro Git β€” Recording Changes](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository) +- [GitHub Docs β€” Using Git](https://docs.github.com/en/get-started/using-git) -> Do all of this inside your `git-practice` repo (or the `Exercises/` folder). Make junk files freely β€” this is a playground. +> Work only inside your disposable `git-github-lab` repository from [`../STUDENT_LAB.md`](../STUDENT_LAB.md). --- -## Lesson 4 β€” The Three Areas + `git status` +## Lesson 4 β€” Working tree, staging area, repository, and `git status` ### LEARN -Git has three "places" a change can be: -1. **Working directory** β€” your actual files, where you edit. -2. **Staging area** β€” a "loading dock" where you gather the changes you want in your next commit. -3. **Repository** β€” the permanent history of commits. -The flow: edit β†’ **add** (stage) β†’ **commit** (save to history). -`git status` is your map β€” it tells you which area things are in. Run it constantly. +For beginner work, use this three-part model: + +1. **Working tree** β€” the files you currently see and edit. +2. **Staging area (index)** β€” the exact snapshot you are preparing for the next commit. +3. **Repository history** β€” commits Git has already recorded. + +```text +edit files + ↓ +working tree + ↓ git add +staging area + ↓ git commit +repository history +``` + +`git status` is your first diagnostic command. It answers questions like: + +- Am I inside a repository? +- Which branch am I on? +- What is untracked? +- What changed but is not staged? +- What is staged for the next commit? + +### PREDICT + +Before running anything, predict what Git will report for the `README.md` you created in Module 0. ### DO + +```bash +git status +git status --short +``` + +`git status --short` is a compact view you will learn to recognize later. Normal `git status` is clearer while you are new. + +Create another file: + ```bash -echo "hello" > notes.txt # create a file -git status # see notes.txt as "untracked" +echo "first experiment" > notes.txt +git status ``` +### EXPLAIN + +Why are these files not yet part of Git history even though Git can see them? + ### TRANSITION CONDITION -You can name the three areas and explain what `git status` tells you. + +Without the guide, explain the three-part model and use `git status` to identify the current branch and untracked files. --- -## Lesson 5 β€” `add`, `commit`, and Good Messages +## Lesson 5 β€” Stage deliberately, inspect the staged snapshot, then commit ### LEARN -- `git add` moves changes to the staging area. -- `git commit` saves a snapshot of staged changes, with a message. -- A good commit message says **what changed and why**, briefly. Use the present tense: *"Add login form"*, not *"added stuff"*. + +`git add` does **not** mean β€œupload.” It copies the selected version of a change into Git's staging area for the next commit. + +A professional habit is: + +> **inspect β†’ stage intentionally β†’ inspect staged diff β†’ commit** + +`git add .` is convenient, but blindly staging everything can accidentally include debug files, generated files, credentials, or unrelated changes. Learn selective staging first. ### DO + +Stage only `README.md`: + ```bash -git add notes.txt -git status # notes.txt is now "staged" -git commit -m "Add notes file" -git status # clean! nothing to commit +git add README.md +git status ``` -Now edit the file and do it again: + +Inspect exactly what is staged: + ```bash -echo "second line" >> notes.txt -git add . -git commit -m "Add a second line to notes" +git diff --staged ``` +Notice `notes.txt` is still untracked. + +Commit the staged snapshot: + +```bash +git commit -m "Add student lab README" +git status +``` + +Now stage and commit `notes.txt` separately: + +```bash +git add notes.txt +git diff --staged +git commit -m "Add experiment notes" +``` + +### COMMIT MESSAGE RULE + +For this course, use concise messages that describe one coherent change: + +```text +Add student lab README +Document fetch experiment +Fix conflict exercise instructions +``` + +Avoid messages like `stuff`, `update`, or `final final 2`. + ### TRANSITION CONDITION -**From memory:** create a file, stage it, and commit it with a clear message. Then change it and commit again. + +From memory: create a file, inspect status, stage only that file, inspect it with `git diff --staged`, and commit it with a useful message. --- -## Lesson 6 β€” Viewing History: `log`, `diff`, `show` +## Lesson 6 β€” Unstaged vs staged diffs, history, and `HEAD` ### LEARN -- `git log` shows your commit history (newest first). -- `git log --oneline` is the compact version. -- `git diff` shows changes you haven't staged yet. -- `git show ` shows what a specific commit changed. + +These commands answer different questions: + +- `git diff` β€” what changed in the working tree compared with the staged/recorded state? +- `git diff --staged` β€” what will the next commit contain? +- `git log` β€” what commits exist in history? +- `git show ` β€” what does one commit contain/change? +- `HEAD` β€” normally the commit your currently checked-out branch points to. ### DO + +```bash +echo "unstaged change" >> notes.txt +git diff +``` + +Now stage it: + +```bash +git add notes.txt +git diff +git diff --staged +``` + +Notice how the change moved from the unstaged diff to the staged diff. + +Commit it, then inspect history: + +```bash +git commit -m "Expand experiment notes" +git log --oneline --decorate +git show HEAD +``` + +Optional visual history: + ```bash -git log -git log --oneline -echo "third line" >> notes.txt -git diff # see the unstaged change -git show HEAD # HEAD = your most recent commit +git log --oneline --graph --decorate --all ``` -(Press `q` to exit the log/diff viewer.) ### TRANSITION CONDITION -You can read your commit history with `git log --oneline` and explain what `git diff` is showing you. + +Given an edited file, you can determine whether its change is unstaged or staged and choose the correct diff command to inspect it. --- -## Lesson 7 β€” `.gitignore` +## Lesson 7 β€” `.gitignore`: prevent untracked noise, not erase history ### LEARN -Some files should NEVER be tracked: secrets (`.env`), dependencies (`node_modules/`), system junk (`.DS_Store`). A `.gitignore` file lists patterns Git should ignore. + +`.gitignore` tells Git which **untracked** paths it should normally ignore. + +Common examples: + +- dependency/build directories +- temporary logs +- local environment files +- editor/OS noise + +Critical rule: + +> Adding a tracked file to `.gitignore` does **not** remove it from history or automatically stop tracking it. + +Also, `.gitignore` is convenienceβ€”not a security system. Never commit real secrets and assume adding them to `.gitignore` later makes them safe. ### DO -1. Create a file named `.gitignore` with these lines: -``` -node_modules/ + +Create `.gitignore`: + +```text .env *.log -.DS_Store +scratch/ ``` -2. Make a file that should be ignored and confirm Git skips it: + +Create ignored files/directories, then inspect: + ```bash -echo "secret" > .env -git status # .env should NOT appear (it's ignored) -git add . -git commit -m "Add gitignore" +echo "fake-local-value" > .env +echo "debug" > debug.log +mkdir scratch +echo "temporary" > scratch/temp.txt +git status +``` + +They should not appear as normal untracked files. + +Ask Git why a path is ignored: + +```bash +git check-ignore -v .env +``` + +Stage **only** `.gitignore` after inspecting: + +```bash +git add .gitignore +git diff --staged +git commit -m "Ignore local scratch files" ``` ### TRANSITION CONDITION -You can create a `.gitignore`, add a pattern, and confirm a matching file no longer shows up in `git status`. + +You can add an ignore rule, verify it with `git status` / `git check-ignore`, and explain why `.gitignore` cannot erase a secret that was already committed. --- -## Lesson 8 β€” Core Loop Checkpoint +## Lesson 8 β€” Core loop checkpoint: make a clean history -### LEARN -You now know the full local loop: **status β†’ add β†’ commit β†’ log**. This is what you'll do every working day. +### GOAL -### DO -In your Exercises folder, run a full cycle from scratch with no guide: -- make 2 files, stage one, commit it -- edit it, view the diff, commit again -- add a `.gitignore` that hides a junk file -- view your history with `git log --oneline` +Prove you can operate the local loop without blindly typing commands. + +### DO β€” CLOSED GUIDE + +In your lab, create three sensible changes but commit them as **two coherent commits**. + +For each commit: + +1. inspect with `git status` +2. inspect the relevant working-tree diff +3. stage only the intended paths +4. inspect with `git diff --staged` +5. commit with a useful message +6. inspect history afterward + +Use: + +```bash +git status +git diff +git add +git diff --staged +git commit -m "..." +git log --oneline --decorate +``` + +### DEBUG CHALLENGE + +Stage a file, then edit it **again before committing**. + +Run: + +```bash +git status +git diff +git diff --staged +``` + +Explain why the same file can have both staged and unstaged changes at once. ### TRANSITION CONDITION -**The big one:** run the entire core loop (create β†’ status β†’ add β†’ commit β†’ diff β†’ log β†’ .gitignore) from memory, no guide open, explaining each step out loud. + +From memory, create two focused commits and explain what each of these represents: + +- working-tree change +- staged change +- commit +- `HEAD` --- -## Module 1 Complete When... -- [ ] You understand the three areas -- [ ] You can stage and commit confidently with good messages -- [ ] You can read history and diffs -- [ ] You can use `.gitignore` -- [ ] **All Transition Conditions passed β†’ start Module 2** +## Module 1 gate + +You are ready for branching when you can: + +- [ ] use `git status` as your first diagnostic +- [ ] distinguish working-tree, staged, and committed state +- [ ] inspect with `git diff` and `git diff --staged` +- [ ] stage intentionally instead of reflexively using `git add .` +- [ ] make focused commits with useful messages +- [ ] inspect history and `HEAD` +- [ ] use `.gitignore` without treating it as a secret-removal tool + +Then complete **Gate 1 β€” Local Git Fundamentals** in [`../ASSESSMENTS.md`](../ASSESSMENTS.md) before Module 2. \ No newline at end of file From fc6033c9e0d15ae1a85db5d01f63415f36b0d213 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:09:58 +0600 Subject: [PATCH 10/17] Upgrade branching mental models and merge practice --- Module_2_Branching/Module_2_Guide.md | 240 ++++++++++++++++++++++----- 1 file changed, 196 insertions(+), 44 deletions(-) diff --git a/Module_2_Branching/Module_2_Guide.md b/Module_2_Branching/Module_2_Guide.md index 8c41042..bc1512b 100644 --- a/Module_2_Branching/Module_2_Guide.md +++ b/Module_2_Branching/Module_2_Guide.md @@ -1,94 +1,246 @@ -# MODULE 2 β€” Branching & Merging (Lessons 9-12) +# MODULE 2 β€” Branching & Merging (Lessons 9–12) -**Goal:** Work on changes safely in separate branches and combine them back into `main`. Branching is how real teams (and smart solo devs) avoid breaking working code. +**Goal:** Isolate work on branches, understand what a branch actually points to, compare lines of history, and merge deliberately without treating branches as mysterious copies of folders. -**Resources:** -- Git book Ch.3 "Branching": https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell -- Learn Git Branching (visual game): https://learngitbranching.js.org/ +**Primary references:** +- [Pro Git β€” Branching](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) +- [Learn Git Branching](https://learngitbranching.js.org/) β€” optional visual practice + +> Continue inside your disposable `git-github-lab` repository. --- -## Lesson 9 β€” What Branches Are + Create/Switch +## Lesson 9 β€” Branches are movable names for commits ### LEARN -A **branch** is a separate line of work. `main` is your stable version. You make a new branch to try something, and `main` stays safe. A branch is just a movable pointer to a commit β€” cheap and fast. + +A Git branch is not a second physical copy of your project. It is a lightweight name/reference that normally points to one commit. + +When you commit while a branch is checked out, that branch name moves forward to the new commit. + +`HEAD` normally tells Git which branch you currently have checked out. + +```text +A---B---C main, HEAD +``` + +After: + +```bash +git switch -c experiment +``` + +both names initially point to the same commit: + +```text +A---B---C main, experiment, HEAD -> experiment +``` ### DO + ```bash -git branch # list branches; * marks where you are -git switch -c feature-x # create AND switch to a new branch -git branch # now you're on feature-x +git branch +git switch -c experiment +git branch +git log --oneline --decorate -5 ``` -(Older syntax that does the same: `git checkout -b feature-x`.) + +Inspect the decoration on the latest commit. You should see both `main` and `experiment` before you make a new commit. + +### PREDICT + +If you now commit on `experiment`, which branch name will move: `experiment`, `main`, or both? ### TRANSITION CONDITION -You can create a new branch, switch to it, and confirm which branch you're on with `git branch`. + +Create and switch branches from memory and explain, without using β€œcopy of a folder,” what a branch is. --- -## Lesson 10 β€” Committing on a Branch +## Lesson 10 β€” Divergence and comparing branches ### LEARN -Commits you make on a branch stay on that branch. `main` doesn't change until you merge. This is the safety of branches. + +Commits belong to history; branches point into that history. Once one branch receives a new commit and another does not, their tips differ. ### DO + +On `experiment`: + +```bash +echo "experiment branch" > experiment.txt +git add experiment.txt +git diff --staged +git commit -m "Add experiment file" +``` + +Inspect: + ```bash -# on feature-x: -echo "experimental feature" > feature.txt -git add . -git commit -m "Add experimental feature" +git log --oneline --graph --decorate --all +git diff main..experiment +``` + +Switch to `main`: +```bash git switch main -ls # feature.txt is GONE here β€” it only exists on feature-x -git switch feature-x -ls # it's back +git status +``` + +`experiment.txt` may disappear from the working tree because the checked-out commit on `main` does not contain it. + +Now create a different commit on `main`: + +```bash +echo "main branch" > main-note.txt +git add main-note.txt +git commit -m "Add main branch note" +git log --oneline --graph --decorate --all ``` +Now the history truly **diverges**. + +### EXPLAIN + +Why did switching branches change visible files without deleting history? + ### TRANSITION CONDITION -You can make commits on a branch and demonstrate that `main` is unaffected until you merge. + +Demonstrate two branches with different commits and use the graph/diff commands to explain how they differ. --- -## Lesson 11 β€” Merging +## Lesson 11 β€” Merge deliberately: fast-forward vs merge commit ### LEARN -`git merge` brings a branch's commits into your current branch. Two common cases: -- **Fast-forward:** `main` hasn't changed, so Git just slides `main` forward. Clean. -- **Merge commit:** both branches changed; Git creates a new commit that ties them together. -### DO +`git merge ` integrates the named branch **into the branch you are currently on**. + +That direction matters. + +Two common outcomes: + +- **Fast-forward** β€” your current branch is simply behind the other branch with no independent commits, so its pointer can move forward. +- **Three-way merge** β€” the branches diverged, so Git combines their histories. If changes do not conflict, Git can create a merge commit automatically. + +A merge commit is not inherently better or worse than a linear history. Teams choose workflows deliberately. + +### DO β€” merge the divergent history you created + +Make sure you are on `main`: + +```bash +git switch main +git status +``` + +Before merging, inspect: + +```bash +git log --oneline --graph --decorate --all +``` + +Merge: + +```bash +git merge experiment +``` + +If no conflict exists, Git should combine the histories. + +Inspect again: + ```bash -git switch main # go to the branch you want to merge INTO -git merge feature-x # bring feature-x's work into main -ls # feature.txt is now on main -git log --oneline # see the merged history +git log --oneline --graph --decorate --all +git status ``` +### FAST-FORWARD MINI-DEMO + +Create a branch from the current `main`, add one commit, then return to unchanged `main` and merge it: + +```bash +git switch -c ff-demo +echo "fast forward" > ff-demo.txt +git add ff-demo.txt +git commit -m "Add fast-forward demo" +git switch main +git merge ff-demo +``` + +Compare this graph with the divergent merge. + ### TRANSITION CONDITION -You can merge a feature branch into `main` and confirm the work arrived. + +You can state which branch receives the merge, predict whether a simple scenario can fast-forward, and verify the result using the commit graph. --- -## Lesson 12 β€” Deleting Branches + Practice +## Lesson 12 β€” Branch lifecycle, safe deletion, and branch inspection ### LEARN -Once a branch is merged, delete it to keep things tidy. `git branch -d ` deletes a merged branch safely (it refuses if there's unmerged work, which protects you). + +Branches are cheap and normally short-lived for focused work. + +Useful inspection commands: + +```bash +git branch +git branch -vv +git branch --merged +git branch --no-merged +``` + +`git branch -d ` is the safer delete: Git refuses in common cases where the branch tip has not been merged into the current history. + +`git branch -D ` forces deletion of the branch name and can make work harder to find. You do not need it in normal beginner workflow. + +Deleting a branch does **not necessarily erase the commit objects immediately**, but do not rely on that as a backup strategy. ### DO + +Inspect before deleting: + ```bash -git branch -d feature-x -git branch # it's gone +git branch --merged +git branch -vv ``` -Then practice the whole flow on your own: branch β†’ commit β†’ switch β†’ merge β†’ delete. + +Then delete your merged demo branches: + +```bash +git branch -d experiment +git branch -d ff-demo +``` + +### CLOSED-GUIDE PRACTICE + +From `main`: + +1. create a focused feature branch +2. make two coherent commits +3. compare it with `main` +4. merge it deliberately +5. inspect the graph +6. safely delete the merged branch ### TRANSITION CONDITION -**From memory:** create a branch, commit on it, merge it into `main`, and delete it β€” explaining each step. + +Perform the full branch lifecycle from memory and explain why deleting a branch name is different from deleting files in your working tree. --- -## Module 2 Complete When... -- [ ] You can create and switch branches -- [ ] You understand commits are isolated to their branch -- [ ] You can merge a branch into `main` -- [ ] You can delete a merged branch -- [ ] **All Transition Conditions passed β†’ start Module 3** +## Module 2 gate + +You are ready for remotes when you can: + +- [ ] explain branch and `HEAD` accurately +- [ ] create/switch branches and inspect them +- [ ] create and recognize divergent history +- [ ] compare branches before merging +- [ ] explain fast-forward vs three-way merge at a beginner level +- [ ] merge in the correct direction +- [ ] safely delete merged branches + +Then complete **Gate 2 β€” Branching** in [`../ASSESSMENTS.md`](../ASSESSMENTS.md) before Module 3. \ No newline at end of file From efda32dbec628c6b18802e08a0fd96a0e2583a2f Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:10:28 +0600 Subject: [PATCH 11/17] Upgrade remotes, tracking, and fetch-pull mental models --- Module_3_Remotes/Module_3_Guide.md | 282 ++++++++++++++++++++++++----- 1 file changed, 234 insertions(+), 48 deletions(-) diff --git a/Module_3_Remotes/Module_3_Guide.md b/Module_3_Remotes/Module_3_Guide.md index 9deef6f..68de07b 100644 --- a/Module_3_Remotes/Module_3_Guide.md +++ b/Module_3_Remotes/Module_3_Guide.md @@ -1,97 +1,283 @@ -# MODULE 3 β€” Remotes: Connecting to GitHub (Lessons 13-16) +# MODULE 3 β€” Remotes: Connecting Local Git to GitHub (Lessons 13–16) -**Goal:** Move your work between your computer and GitHub β€” clone, push, pull, fetch. This is how your code gets backed up and shared. +**Goal:** Understand the relationship between your local repository and remote repositories, then deliberately clone, fetch, pull, push, and inspect tracking relationships. -**Resources:** -- Git book Ch.2 "Working with Remotes": https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes -- GitHub Docs β€” push to remote: https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository +**Primary references:** +- [Pro Git β€” Working with Remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) +- [GitHub Docs β€” Using Git](https://docs.github.com/en/get-started/using-git) --- -## Lesson 13 β€” Remotes Concept + Clone +## Lesson 13 β€” Remotes, `origin`, remote-tracking branches, and clone ### LEARN -A **remote** is a version of your repo hosted elsewhere (usually GitHub). The default remote is named **`origin`**. -- `git clone ` copies a GitHub repo (and its full history) to your computer. + +A **remote** is a saved name for another Git repository URL. + +`origin` is only a conventional name. It is not a special server and it does not mean β€œGitHub” by definition. + +When you clone a normal repository, Git usually: + +1. creates a local repository +2. downloads the remote history +3. adds a remote named `origin` +4. creates remote-tracking references such as `origin/main` +5. checks out a local branch that tracks the remote branch + +A useful model: + +```text +local main <- branch you can commit on +origin/main <- your local record of where remote main was at last fetch +GitHub main <- branch that actually exists on the remote server +``` + +`origin/main` does not magically update every second. `git fetch` refreshes your remote-tracking references. ### DO -1. On GitHub, find any small public repo (or one of your own) and click the green **Code** button β†’ copy the HTTPS URL. -2. Clone it: + +Clone one of your own disposable repositories or another small public repo: + ```bash -git clone +git clone cd -git remote -v # shows 'origin' pointing at the URL +git remote -v +git branch -vv +git log --oneline --decorate -5 +``` + +Inspect the remote configuration: + +```bash +git remote show origin ``` ### TRANSITION CONDITION -You can clone a repo from GitHub and show its remote with `git remote -v`. + +You can explain the difference between local `main`, `origin/main`, and the remote GitHub branch, and you can inspect a cloned repo's remote/tracking setup. --- -## Lesson 14 β€” Push (Send Your Work Up) +## Lesson 14 β€” Publish your lab and understand upstream tracking ### LEARN -`git push` sends your local commits to GitHub. The first time on a new branch, use `-u` to set the "upstream" so future pushes are just `git push`. + +`git push` transfers commits/refs to a remote repository when the remote accepts them. + +On the first push of a local branch, this is common: + +```bash +git push -u origin main +``` + +`-u` / `--set-upstream` records the tracking relationship. After that, plain `git push` and `git pull` usually know which branch to use. + +Before pushing, ask: + +- Did I inspect my commits? +- Am I pushing the intended branch? +- Is the remote URL correct? +- Could this contain credentials/private data? ### DO -1. On GitHub, create a NEW empty repo (no README). Copy its URL. -2. In your local `git-practice` repo: + +Create an **empty** GitHub repository for your lab. Do not initialize it with files if your local lab already has history. + +Inside `git-github-lab`: + ```bash -git remote add origin # link local repo to GitHub -git push -u origin main # first push, sets upstream +git remote add origin +git remote -v +git branch -vv +git log --oneline --decorate -5 ``` -3. Refresh the GitHub page β€” your files are there! -4. Make a change locally, commit it, then: + +Push: + +```bash +git push -u origin main +``` + +Inspect tracking again: + ```bash -git push # no -u needed now +git branch -vv +git status +``` + +Make one small local commit and push again: + +```bash +git push +``` + +### DEBUG CHECK + +If `git remote add origin ...` says `origin already exists`, do **not** keep adding random remotes. Inspect first: + +```bash +git remote -v +``` + +If the URL is wrong, change it deliberately: + +```bash +git remote set-url origin ``` ### TRANSITION CONDITION -You can link a local repo to a GitHub repo and push commits so they appear on GitHub. + +From memory, connect a local repo to an empty GitHub repo, set upstream on the first push, and use `git branch -vv` to explain the tracking relationship. --- -## Lesson 15 β€” Pull vs Fetch (Get Work Down) +## Lesson 15 β€” Fetch first: inspect before integrating ### LEARN -- `git fetch` downloads new commits from GitHub but does NOT change your files yet (safe look). -- `git pull` = `fetch` + `merge` β€” downloads AND updates your files in one step. + +`git fetch` contacts the remote and updates remote-tracking refs such as `origin/main` **without integrating those commits into your current branch**. + +`git pull` performs a fetch and then integrates according to configuration/options. A common default is merge, but repositories/users may configure rebase or fast-forward-only behavior. + +So the durable mental model is: + +> **fetch = update knowledge of the remote** +> +> **pull = fetch + integrate into the current branch according to the chosen pull strategy** + +When uncertain, fetching first gives you a chance to inspect. ### DO -1. On GitHub, edit a file directly in the browser (pencil icon) and commit it. -2. Back in your terminal: + +On GitHub, edit a harmless file in your lab repo and create a commit there. + +Back locally, before fetching: + ```bash -git fetch # downloads the change, your files unchanged yet -git status # tells you you're "behind" -git pull # now your local files update +git status +git log --oneline --decorate --graph --all -8 +``` + +Fetch: + +```bash +git fetch origin +``` + +Inspect again: + +```bash +git status +git log --oneline --decorate --graph --all -8 +git log main..origin/main --oneline +git diff main..origin/main +``` + +If your local `main` has not independently diverged, integrate: + +```bash +git pull +``` + +Then inspect: + +```bash +git status +git log --oneline --decorate --graph --all -8 ``` ### TRANSITION CONDITION -You can explain the difference between `fetch` and `pull`, and use `pull` to bring GitHub changes to your computer. + +You can fetch without changing your checked-out files, inspect commits that exist on `origin/main` but not `main`, and explain why `pull` is more than β€œdownload.” --- -## Lesson 16 β€” The Full Local/Remote Loop +## Lesson 16 β€” Full round trip + divergence awareness ### LEARN -The everyday remote loop: `pull` (get latest) β†’ work β†’ `add`/`commit` β†’ `push`. Pull before you start, push when you're done. -### DO -From scratch, with no guide: -- create a new GitHub repo -- connect a local folder to it -- push some commits -- edit on GitHub, then pull the change down -- make a local change and push it back +A healthy solo loop is often: + +```text +inspect remote/local state + ↓ +fetch / pull when appropriate + ↓ +edit + ↓ +status + diff + ↓ +stage deliberately + ↓ +diff --staged + ↓ +commit + ↓ +push +``` + +But Git becomes interesting when both sides changed. If local `main` and remote `main` contain different new commits, the histories have **diverged**. Blindly repeating `push`, `pull`, or force commands is not the solution; inspect the graph first. + +### CLOSED-GUIDE ROUND TRIP + +Perform this from memory: + +1. fetch and verify your lab is up to date +2. make and push a local commit +3. create a different browser-side GitHub commit +4. fetch it locally +5. inspect the graph and remote-tracking ref +6. integrate it safely +7. make another local commit and push + +### DIVERGENCE SIMULATION + +Create one local commit but **do not push it yet**. + +Then create a separate commit on GitHub through the browser. + +Back locally: + +```bash +git fetch +git status +git log --oneline --graph --decorate --all -10 +``` + +You should now see local and remote tips that are not identical. + +Do not use force push. For this course, integrate conservatively: + +```bash +git pull --no-rebase +``` + +If Git creates a normal merge or reports a conflict, inspect carefully. Module 6 covers conflict handling in depth. + +Then: + +```bash +git push +git log --oneline --graph --decorate --all -10 +``` ### TRANSITION CONDITION -**From memory:** complete a full round trip β€” local commit β†’ push β†’ edit on GitHub β†’ pull β†’ push again. + +You can complete a local↔GitHub round trip, recognize divergence in the graph, and explain why force-pushing is not a beginner fix for rejected pushes. --- -## Module 3 Complete When... -- [ ] You can clone a repo -- [ ] You can connect a local repo to GitHub and push -- [ ] You understand and can use fetch vs pull -- [ ] You can do a full local/remote round trip -- [ ] **All Transition Conditions passed β†’ start Module 4** +## Module 3 gate + +You are ready for collaboration when you can: + +- [ ] explain remotes and why `origin` is only a name +- [ ] distinguish `main`, `origin/main`, and the remote branch +- [ ] inspect remotes with `git remote -v` / `git remote show origin` +- [ ] publish a branch and set upstream +- [ ] use `fetch` to inspect before integrating +- [ ] describe `pull` accurately as fetch + configured integration +- [ ] recognize diverged local/remote history +- [ ] complete a safe round trip without force-pushing + +Then complete **Gate 3 β€” Remote Round Trip** in [`../ASSESSMENTS.md`](../ASSESSMENTS.md) before Module 4. \ No newline at end of file From 024e62666402449326edc378056fe000a5385a05 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:10:58 +0600 Subject: [PATCH 12/17] Upgrade collaboration and contribution workflow --- Module_4_Collaboration/Module_4_Guide.md | 258 +++++++++++++++++++---- 1 file changed, 218 insertions(+), 40 deletions(-) diff --git a/Module_4_Collaboration/Module_4_Guide.md b/Module_4_Collaboration/Module_4_Guide.md index 8969bad..77a2fcb 100644 --- a/Module_4_Collaboration/Module_4_Guide.md +++ b/Module_4_Collaboration/Module_4_Guide.md @@ -1,89 +1,267 @@ -# MODULE 4 β€” Collaboration (Lessons 17-20) +# MODULE 4 β€” Collaboration (Lessons 17–20) -**Goal:** Work with others (and your future self) the way real teams do: forks, Pull Requests, code review, and Issues. This is the part of GitHub that gets you hired. +**Goal:** Learn the collaboration workflow used on real GitHub projects: fork/clone when appropriate, branch, commit, push, open a Pull Request, review changes, respond to feedback, and connect work to Issues. -**Resources:** -- GitHub Docs β€” About Pull Requests: https://docs.github.com/en/pull-requests -- GitHub Docs β€” About forks: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks -- First Contributions (practice repo): https://github.com/firstcontributions/first-contributions +**Primary references:** +- [GitHub Docs β€” Pull Requests](https://docs.github.com/en/pull-requests) +- [GitHub Docs β€” Forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks) +- [GitHub Docs β€” Issues](https://docs.github.com/en/issues) --- -## Lesson 17 β€” Forks vs Clones +## Lesson 17 β€” Fork vs clone vs branch: choose the right boundary ### LEARN -- **Clone** = copy a repo to your computer. -- **Fork** = make your OWN copy of someone else's repo *on GitHub*, under your account. You fork when you want to contribute to a project you don't own. -- Typical flow: **Fork** (on GitHub) β†’ **Clone** your fork (to your computer) β†’ work β†’ push to your fork β†’ open a Pull Request to the original. + +These are different operations: + +- **branch** β€” a line of development inside one Git repository +- **clone** β€” create a local copy of a Git repository and its history +- **fork** β€” create a GitHub-hosted repository under another account/namespace based on an existing repository + +You do **not** need to fork every repository you work on. + +Typical cases: + +```text +Your own repo / collaborator access + clone β†’ branch β†’ push β†’ PR + +External project without write access + fork β†’ clone your fork β†’ branch β†’ push β†’ PR to upstream project +``` + +Before contributing to an external project, read its `README`, `CONTRIBUTING.md`, issue/PR templates, code of conduct, and any maintainer instructions. A technically correct change can still be an unwanted contribution if you ignore project rules. ### DO -1. Go to https://github.com/firstcontributions/first-contributions -2. Click **Fork** (top right). Now there's a copy under `your-username/first-contributions`. -3. Clone YOUR fork: + +Choose a practice repository that explicitly welcomes beginner contributions, such as: + + + +Fork it on GitHub, then clone **your fork**: + ```bash git clone cd first-contributions +git remote -v +``` + +Add the original project as a second remote named `upstream`: + +```bash +git remote add upstream +git remote -v ``` +Mental model: + +```text +origin = your fork +upstream = original project +``` + +Those names are conventions, not magic. + ### TRANSITION CONDITION -You can explain the difference between fork and clone, and you've forked + cloned a repo. + +Explain when you need a fork and when a normal branch is enough. Show `origin` and `upstream` in a fork-based practice repository. --- -## Lesson 18 β€” Creating a Pull Request +## Lesson 18 β€” Create a focused Pull Request ### LEARN -A **Pull Request (PR)** says: *"I made some changes on a branch β€” please review and merge them."* It's the standard way to propose changes. Always work on a branch, not directly on `main`. + +A Pull Request is a GitHub collaboration object that proposes merging one branch into another and provides a place for diff review, discussion, checks, and approval. + +A good beginner PR is: + +- small +- focused on one purpose +- based on project instructions +- easy to review +- explained clearly + +Do not mix unrelated cleanup into a PR just because you noticed it. ### DO + +Before changing anything: + ```bash +git status git switch -c add-my-name -# edit the Contributors file to add your name (follow the repo's README) -git add . +``` + +Make the contribution required by the practice repo. + +Inspect before committing: + +```bash +git status +git diff +git add +git diff --staged git commit -m "Add to contributors" +``` + +Inspect history and push the branch: + +```bash +git log --oneline --decorate -5 git push -u origin add-my-name ``` -Then on GitHub: you'll see a **"Compare & pull request"** button β†’ click it β†’ write a title and description β†’ **Create pull request**. + +On GitHub, open the Pull Request. In the description explain: + +- what changed +- why +- anything the reviewer should know + +If the project has a PR template, follow it instead of deleting it. ### TRANSITION CONDITION -You can push a branch and open a Pull Request from it on GitHub. + +From memory, create a focused branch, inspect/stage/commit only the intended change, push the branch, and open a clear PR. --- -## Lesson 19 β€” Code Review + Merging a PR +## Lesson 19 β€” Review the diff, respond to feedback, update the same PR ### LEARN -On a PR, reviewers leave **comments** on specific lines, request changes, or approve. When approved, someone **merges** it. You respond to comments by pushing more commits to the same branch β€” the PR updates automatically. + +PR review is not an exam. It is a collaboration process around the proposed change. + +Reviewers may: + +- comment on lines +- ask questions +- request changes +- approve +- rely on automated checks + +When you push another commit to the **same PR branch**, GitHub updates the PR automatically. + +A useful response pattern is: + +1. understand the feedback +2. ask if unclear +3. make the smallest appropriate change +4. inspect it locally +5. commit and push to the same branch +6. reply explaining what changed + +Do not resolve review comments you do not actually understand just to make the UI green. ### DO -1. On your own PR (or a practice repo), explore the **Files changed** tab. -2. Add a comment on a line. -3. Make another commit on the branch and push β€” watch the PR update. -4. If it's your repo, click **Merge pull request** to merge it. + +On your own practice repository, create a second account/collaborator scenario if availableβ€”or simulate review on a PR you own. + +Inspect the tabs: + +- Conversation +- Commits +- Checks (if present) +- Files changed + +Read the actual diff before merging. + +Make one improvement on the PR branch: + +```bash +git switch +# edit + +git diff +git add +git diff --staged +git commit -m "Address review feedback" +git push +``` + +Refresh the PR and confirm the new commit/diff appears. + +### MERGE METHODS β€” RECOGNIZE, DON'T WORSHIP + +GitHub commonly offers: + +- merge commit +- squash and merge +- rebase and merge + +Different projects choose different history policies. As a contributor, follow the repository's convention. You do not need one universal β€œbest” merge method. ### TRANSITION CONDITION -You can read a PR's diff, leave a review comment, update a PR with a new commit, and merge it. + +You can inspect a PR diff, update an existing PR by pushing another commit, and explain why review feedback changes the branch rather than requiring a brand-new PR. --- -## Lesson 20 β€” Issues + Linking PRs +## Lesson 20 β€” Issues, linking work, and contribution etiquette ### LEARN -**Issues** are tickets: bug reports, feature ideas, tasks. You can link a PR to an issue so merging the PR auto-closes the issue (write `Closes #12` in the PR description). -### DO -1. In one of your repos, open the **Issues** tab β†’ **New issue** β†’ describe a small task. -2. Create a branch, make the change, open a PR, and write `Closes #1` in the description. -3. Merge the PR β†’ watch the issue close automatically. +Issues can represent bugs, feature requests, investigations, or tasksβ€”but repositories use Issues differently. + +Before opening one: + +- search existing Issues +- read templates/instructions +- confirm the repo actually accepts the type of request +- provide reproduction/context instead of β€œit doesn't work” + +Closing keywords such as: + +```text +Closes #12 +Fixes #12 +Resolves #12 +``` + +can connect a PR to an Issue and, in supported same-repository/default-branch workflows, automatically close it when the PR is merged. + +### DO β€” YOUR OWN PRACTICE REPO + +Use a repo you own so you can safely exercise the complete lifecycle: + +1. open an Issue describing a small change with acceptance criteria +2. create a branch named after the task +3. make the change +4. open a PR +5. reference the issue with `Closes #` +6. inspect the PR diff +7. merge it +8. confirm the issue state afterward + +### OPEN-SOURCE ETIQUETTE CHECK + +Before the capstone, be able to answer: + +- Did the maintainers ask for an Issue before a PR? +- Is this issue already assigned? +- Is there a contribution guide? +- Am I changing only what the PR claims to change? +- Did I run whatever validation the project asks for? +- Am I comfortable if maintainers decline the contribution? ### TRANSITION CONDITION -You can open an Issue and close it automatically by merging a linked PR. + +Create and complete an Issueβ†’branchβ†’PRβ†’reviewβ†’merge loop in a repository you control, and explain how you would behave differently in someone else's project. --- -## Module 4 Complete When... -- [ ] You understand fork vs clone and the contribution flow -- [ ] You can open a Pull Request -- [ ] You can review, update, and merge a PR -- [ ] You can use Issues and link them to PRs -- [ ] **All Transition Conditions passed β†’ start Module 5** +## Module 4 gate + +You are ready for recovery when you can: + +- [ ] distinguish branch, clone, and fork +- [ ] use `origin` and `upstream` in a fork workflow +- [ ] read contribution instructions before changing an external project +- [ ] open a focused PR from a branch +- [ ] inspect a PR diff and respond to review feedback +- [ ] recognize common merge methods without assuming one is universally correct +- [ ] use Issues and PR links deliberately +- [ ] describe respectful open-source contribution etiquette + +Then complete **Gate 4 β€” Collaboration** in [`../ASSESSMENTS.md`](../ASSESSMENTS.md) before Module 5. \ No newline at end of file From 0fd7b8adf7603a323119bdbfa1697bf03fe0d61f Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:11:26 +0600 Subject: [PATCH 13/17] Make Git cheatsheet safer and more diagnostic --- CHEATSHEET.md | 342 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 256 insertions(+), 86 deletions(-) diff --git a/CHEATSHEET.md b/CHEATSHEET.md index 4f69078..a0d996f 100644 --- a/CHEATSHEET.md +++ b/CHEATSHEET.md @@ -1,135 +1,305 @@ # Git & GitHub Cheatsheet -> Every command in this course, in one place. Bookmark it. When you forget a command (you will, everyone does), come here. -> `` means "replace this with your own value." Don't type the angle brackets. +> Quick reference for this course. Use it to remember syntaxβ€”not to skip understanding repository state. +> +> `` means β€œreplace this with your own value.” Do not type the angle brackets. ---- +## First response when confused -## Setup (one time) ```bash -git --version # check Git is installed -git config --global user.name "Your Name" # who you are -git config --global user.email "you@email.com" # your email (use your GitHub one) -git config --global init.defaultBranch main # name the first branch "main" -git config --list # see your settings +git status +git branch -vv +git log --oneline --graph --decorate --all -12 ``` -## Start a Project +Then inspect before changing anything. + +--- + +## Setup + ```bash -git init # turn the current folder into a Git repo -git clone # copy a GitHub repo to your computer +git --version +git config --global user.name "Your Name" +git config --global user.email "your-commit-email@example.com" +git config --global init.defaultBranch main +git config --global --list +git config --show-origin --get user.email ``` -## The Daily Core Loop +## Create / copy a repository + ```bash -git status # what's changed? (run this CONSTANTLY) -git add # stage one file for the next commit -git add . # stage everything that changed -git commit -m "message" # save a snapshot with a description -git log # see the history of commits -git log --oneline # history, short version -git diff # see exact changes you haven't staged yet -git show # see what a specific commit changed +git init +git clone +git rev-parse --show-toplevel ``` -## .gitignore +## Daily local workflow + +```bash +git status # overall repository state +git status --short # compact state +git diff # unstaged changes +git add # stage intended path +git diff --staged # inspect next commit snapshot +git commit -m "Useful message" +git log --oneline --decorate +git show HEAD ``` -# Put this in a file named .gitignore to tell Git what to NEVER track: -node_modules/ + +`git add .` is valid, but inspect first. Do not use it reflexively in a messy working tree. + +## `.gitignore` + +Example: + +```text .env *.log -.DS_Store +node_modules/ +scratch/ ``` -## Branching & Merging ```bash -git branch # list branches (the * is where you are) -git branch # create a branch -git switch # move to a branch (modern) -git switch -c # create AND move to a new branch -git checkout # older way to switch -git merge # merge INTO your current branch -git branch -d # delete a merged branch +git check-ignore -v ``` -## Remotes (connecting to GitHub) +`.gitignore` normally affects untracked files. It does not remove an already tracked secret from history. + +## Branching + ```bash -git remote -v # see your linked remotes -git remote add origin # link your repo to a GitHub repo -git push -u origin main # first push (sets the upstream) -git push # send commits to GitHub -git pull # get + merge changes from GitHub -git fetch # get changes WITHOUT merging yet +git branch +git branch -vv +git switch +git switch -c +git diff main.. +git merge # merges INTO your current branch +git branch --merged +git branch --no-merged +git branch -d ``` -## Fixing Mistakes (your safety net) +History graph: + ```bash -git restore # discard unstaged changes to a file -git restore --staged # unstage a file (keep the changes) -git stash # shelve changes temporarily -git stash pop # bring shelved changes back -git commit --amend # fix the LAST commit (message or content) -git reset --soft HEAD~1 # undo last commit, KEEP the changes staged -git reset --hard HEAD~1 # (careful) undo last commit AND delete the changes -git revert # safely undo a commit by making a new one -git reflog # see EVERYTHING you've done (recover lost work) +git log --oneline --graph --decorate --all ``` -> 🟒 Safe to use anytime: `restore`, `stash`, `revert`, `reflog`, `reset --soft` -> πŸ”΄ Can delete work: `reset --hard`, `clean -fd`, `push --force` β€” pause and think first. +## Remotes and GitHub -## Merge Conflicts ```bash -# When Git can't auto-merge, it marks the file like this: -<<<<<<< HEAD -your version -======= -their version ->>>>>>> other-branch -# Edit the file, delete the <<<, ===, >>> lines, keep what you want, then: -git add -git commit # finishes the merge +git remote -v +git remote show origin +git remote add origin +git remote set-url origin +git fetch origin +git branch -vv +git log main..origin/main --oneline +git diff main..origin/main +git push -u origin main +git push +git pull ``` -## Rebase (advanced β€” use carefully) +Mental model: + +- `main` = your local branch +- `origin/main` = your local record of remote `main` from the last fetch +- `origin` = conventional remote name, not magic +- `fetch` = update remote knowledge without integrating into current branch +- `pull` = fetch + integrate using the selected/configured strategy + +## Fork workflow + +Typical external contribution setup: + ```bash -git rebase main # replay your branch's commits on top of main -# GOLDEN RULE: never rebase commits you've already pushed/shared. +git clone +cd +git remote add upstream +git remote -v +git fetch upstream ``` -## Tags & Releases +Common convention: + +```text +origin β†’ your fork +upstream β†’ original project +``` + +## Undo / recovery β€” choose by state + +### Unstage while keeping your edits + ```bash -git tag # list tags -git tag -a v1.0.0 -m "v1.0.0" # create an annotated tag (a version marker) -git push origin v1.0.0 # push a tag to GitHub +git restore --staged ``` -## Inspecting & Recovering +### Discard unstaged file edits β€” DESTRUCTIVE TO THOSE UNCOMMITTED EDITS + ```bash -git log --oneline --graph --all # visual history of all branches -git blame # who changed each line, and when -git reflog # the undo-everything safety log +git diff # inspect first +git restore ``` ---- +### Temporarily shelve work + +```bash +git stash push -m "description" +git stash list +git stash pop +``` + +### Fix the latest local/unshared commit -## GitHub Website Words (so they're not confusing) -- **Repository (repo):** a project folder on GitHub. -- **Fork:** your own copy of someone else's repo. -- **Pull Request (PR):** "please pull my changes into your project" β€” how you propose changes. -- **Issue:** a ticket to report a bug or suggest a feature. -- **Commit:** one saved snapshot of your work. -- **Branch:** a separate line of work, so you don't mess up `main`. -- **Merge:** combining one branch's work into another. +```bash +git commit --amend +``` + +This rewrites that commit. Be careful if it has already been shared. + +### Undo a shared commit while preserving history + +```bash +git revert +``` + +### Move branch history locally + +```bash +git reset --soft HEAD~1 # move branch back, keep changes staged +git reset --mixed HEAD~1 # move back, keep changes unstaged (default mode) +``` + +### Destructive reset + +```bash +git reset --hard +``` + +This can destroy uncommitted working-tree/index changes. Use only in a disposable/recovery exercise when you understand the target. + +### Recover displaced committed work + +```bash +git reflog +git switch -c recovery +``` + +Creating a recovery branch is usually safer for a learner than immediately hard-resetting onto a found hash. + +## Merge conflicts + +When a merge conflicts: + +```bash +git status +``` + +Open conflicted files and resolve the marked regions, then: + +```bash +git add +git status +git commit +``` + +Abort a merge **before completing it** if you want to return to the pre-merge state: + +```bash +git merge --abort +``` + +## Rebase + +```bash +git rebase main +``` + +Rebase rewrites commits. Avoid rewriting shared history unless you understand the consequences and the project workflow expects it. + +Useful abort command during a troubled rebase: + +```bash +git rebase --abort +``` + +## Push rejection / divergence + +Do **not** jump straight to force push. + +Inspect: + +```bash +git fetch +git status +git log --oneline --graph --decorate --all -15 +``` + +Then choose the appropriate integration/recovery strategy. + +## Force push β€” advanced boundary + +If a workflow intentionally requires rewriting a branch you own, `--force-with-lease` is generally safer than raw `--force` because it checks that the remote has not moved unexpectedly: + +```bash +git push --force-with-lease +``` + +This is still history rewriting. It is **not** a generic fix for push errors. + +## Tags and releases + +```bash +git tag +git tag -a v1.0.0 -m "Release v1.0.0" +git show v1.0.0 +git push origin v1.0.0 +``` + +A Git tag points at a Git object/commit. A GitHub Release is a GitHub product object commonly built around a tag with release notes/assets. + +## Helpful inspection + +```bash +git log --oneline --graph --decorate --all +git show +git blame +git reflog +git remote -v +git branch -vv +``` --- -## The 5 commands you'll use 90% of the time +## GitHub vocabulary + +- **Repository** β€” a Git repository hosted on GitHub. +- **Branch** β€” a movable Git reference used for a line of development. +- **Commit** β€” a recorded project snapshot with metadata and parent history. +- **Remote** β€” a saved name for another repository URL. +- **Fork** β€” a GitHub repository created under another namespace from an existing GitHub repository. +- **Pull Request** β€” a GitHub review/discussion workflow proposing branch changes for integration. +- **Issue** β€” a repository discussion/tracking object; projects use them for bugs, tasks, proposals, and more. +- **Merge** β€” integrate histories/changes from another branch into the current branch. +- **Tag** β€” a Git reference commonly used to mark versions. +- **Release** β€” GitHub release metadata/notes/assets commonly associated with a tag. + +## The small set worth developing muscle memory for + ```bash git status -git add . +git diff +git add +git diff --staged git commit -m "message" -git push +git log --oneline --graph --decorate --all +git fetch git pull +git push ``` -Memorize these. The rest you can look up here. + +You do **not** need every Git command memorized. You need to inspect state, understand the operation you are about to perform, and know where to look when you forget syntax. \ No newline at end of file From b6c8f7d4811a84837e0f11b6cf67b84139e8ebf5 Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:11:56 +0600 Subject: [PATCH 14/17] Strengthen capstone with contribution and recovery proof --- Capstone_First_Contribution/README.md | 255 ++++++++++++++++++++++---- 1 file changed, 215 insertions(+), 40 deletions(-) diff --git a/Capstone_First_Contribution/README.md b/Capstone_First_Contribution/README.md index 464f81f..9e3db2f 100644 --- a/Capstone_First_Contribution/README.md +++ b/Capstone_First_Contribution/README.md @@ -1,59 +1,234 @@ -# CAPSTONE β€” Your First Real Open-Source Contribution + Polished Profile +# CAPSTONE β€” Real Contribution + Recovery Proof + GitHub Profile -**Goal:** Prove you can do the whole real-world loop end to end, on a real project you don't own β€” and make your GitHub profile look like someone worth hiring. +**Goal:** Prove you can use Git and GitHub independently in a realistic workflow, recover from mistakes without panic, and present your work professionally. -This capstone has **two parts**. Do both. +This capstone has **three parts**. Complete all three. --- -## Part A β€” Make a Real Contribution +## Part A β€” Make one respectful real contribution -You'll use everything from Modules 0-6: fork β†’ clone β†’ branch β†’ commit β†’ push β†’ Pull Request β†’ respond to review. +Use the full external-contribution workflow: -### Beginner-friendly places to find a first contribution -- **First Contributions** (designed for your first PR): https://github.com/firstcontributions/first-contributions -- **good first issue** (curated easy issues): https://goodfirstissue.dev/ -- **Up For Grabs:** https://up-for-grabs.net/ -- Or: fix a typo / improve docs in ANY repo you use. Docs fixes are real, welcome contributions. +> discover β†’ read project rules β†’ fork if needed β†’ clone β†’ branch β†’ inspect β†’ change β†’ test β†’ commit β†’ push β†’ PR β†’ review -### The steps -1. **Find** a small issue or doc fix (start tiny β€” a typo is a perfectly valid first PR). -2. **Fork** the repo on GitHub. -3. **Clone** your fork to your computer. -4. Create a **branch**: `git switch -c fix-typo-readme` -5. Make the change. Keep it small and focused. -6. **Commit** with a clear message. -7. **Push** your branch to your fork. -8. Open a **Pull Request** to the original repo. Write a clear title + description. If there's a related issue, add `Closes #`. -9. **Respond** to any review feedback by pushing more commits to the same branch. +### Find a contribution -### Part A is complete when... -- [ ] You opened a real Pull Request to a repo you don't own -- [ ] Your PR has a clear title and description -- [ ] (Bonus) It gets merged πŸŽ‰ β€” but opening a clean PR counts as success regardless +Prefer one of these: + +- an explicitly labeled beginner / `good first issue` task +- a documentation correction you can verify +- a small bug with clear reproduction and maintainer interest +- a project you already use and understand enough to improve responsibly + +Practice-only option: [First Contributions](https://github.com/firstcontributions/first-contributions). + +Discovery sites can help you browse, but **the target repository's own contribution instructions are authoritative**. + +### Before touching code + +Check: + +- `README.md` +- `CONTRIBUTING.md` +- open Issues and existing PRs +- issue/PR templates +- code of conduct if present +- whether maintainers want an Issue before implementation +- whether the task is assigned or already being worked on + +Do not open drive-by PRs that create review work without adding useful value. + +### Required workflow + +1. identify one small contribution +2. document why it is appropriate +3. fork only if you lack write access / the project workflow expects a fork +4. clone the correct repository +5. configure `upstream` when using a fork +6. create a focused branch +7. make only the intended change +8. run the project's requested validation +9. inspect `git status`, `git diff`, and staged diff +10. create one or more coherent commits +11. push your branch +12. open a clear PR +13. respond professionally to feedback if any arrives + +### Evidence to save + +In your student workspace, record: + +```text +repository: +issue/task: +branch: +commit(s): +PR URL: +validation performed: +what I learned from review: +``` + +### Part A passes when + +- [ ] you followed the target project's contribution rules +- [ ] your PR is small and understandable +- [ ] commit/PR text explains the change clearly +- [ ] you did not include unrelated cleanup +- [ ] requested validation was performed +- [ ] a real PR exists, even if maintainers ultimately decline or close it + +A merge is great evidence, but maintainers owe you neither a merge nor a response. + +--- + +## Part B β€” Git disaster/recovery practical + +A Git user is not independent if everything is fine only while nothing goes wrong. + +Use your **disposable student lab**, never important work. + +### Scenario 1 β€” recover a displaced commit + +1. create and commit a file called `recovery-proof.txt` +2. record the commit hash +3. make at least one later commit +4. intentionally move the branch backward in the safe disposable environment +5. use `git reflog` to locate the displaced commit +6. recover it by creating a branch: + +```bash +git switch -c recovered-work +``` + +7. verify `recovery-proof.txt` exists there +8. explain what happened to the branch pointer versus the commit + +### Scenario 2 β€” resolve a real merge conflict + +Create two branches that modify the **same line differently after they diverge**. Merge them to produce a conflict. + +You must: + +```bash +git status +``` + +- identify the conflicted path +- inspect the conflict markers +- choose the intended final content +- remove markers +- stage the resolved file +- complete the merge +- inspect the resulting graph + +### Scenario 3 β€” diagnose local/remote divergence + +Create one local commit and one different GitHub-side commit before synchronizing. + +Then: + +```bash +git fetch +git status +git log --oneline --graph --decorate --all +``` + +Explain the graph **before** integrating. Resolve without using raw force push. + +### Part B passes when + +- [ ] you recover a displaced committed change using reflog +- [ ] you resolve a deliberately created merge conflict +- [ ] you diagnose local/remote divergence from the graph +- [ ] you can name which operations in the exercise rewrote/moved history and which preserved it + +--- + +## Part C β€” Build an honest, professional GitHub profile + +The goal is **clarity and evidence**, not pretending to be more experienced than you are. + +### Profile README + +GitHub displays a profile README when you have a public repository whose name exactly matches your username and contains a root `README.md`. + +Your profile should communicate: + +- who you are +- what you are currently building/learning +- what kinds of engineering problems interest you +- a few projects that actually support those claims +- how someone can understand or contact you, if you want that public + +Avoid giant walls of badges or skill logos that imply expertise you cannot demonstrate yet. + +### Repository presentation checklist + +For the strongest repositories you intend to feature: + +- [ ] descriptive name +- [ ] concise repository description +- [ ] useful README +- [ ] clear project status +- [ ] setup/run instructions when relevant +- [ ] screenshots/demo where that genuinely helps +- [ ] no committed secrets +- [ ] understandable commit history +- [ ] license when you intentionally want others to reuse the work + +### Pinning rule + +Pin **evidence**, not clutter. Four strong repositories beat six weak/random ones. + +### Part C passes when + +- [ ] a stranger can understand your current direction quickly +- [ ] every major claim on your profile is supported by evidence or clearly worded as a goal/current learning direction +- [ ] your strongest public repos are easy to understand +- [ ] you understand how the profile README repository works --- -## Part B β€” Polish Your GitHub Profile +# Final oral/practical check + +Without the cheatsheet, explain and demonstrate the relationship between: -Recruiters look at your GitHub. Make the first impression count. +```text +working tree +staging area +commit +branch +HEAD +remote +origin/main +fork +Pull Request +``` -### Checklist -- [ ] **Profile README** β€” a repo named exactly your username, introducing who you are, what you build, and your stack. -- [ ] **Pin your best repos** β€” pin 4-6 projects (your No-Plan-B capstones will go here over time). -- [ ] **Every pinned repo has a good README** β€” what it does, screenshot, live link, how to run. -- [ ] **Clean commit history** β€” clear messages, regular commits. -- [ ] **Profile basics filled in** β€” photo, bio, location, links (LinkedIn/portfolio). +Then explain what you would inspect first in each situation: -### Part B is complete when... -- [ ] Your profile clearly says "this person builds things and knows Git" -- [ ] A stranger could understand what you do in 30 seconds +1. β€œGit says I have changes but I don't know what they are.” +2. β€œMy push was rejected.” +3. β€œI think I lost a commit.” +4. β€œA merge has conflicts.” +5. β€œI staged something I didn't want to commit.” +6. β€œI want to contribute to a repository I don't own.” + +The expected behavior is not memorizing one rescue command. It is **inspect state β†’ understand the boundary β†’ choose the least destructive operation that solves the actual problem**. --- -## 🏁 Course Complete When... -- [ ] Part A: a real Pull Request is open (or merged) -- [ ] Part B: your profile is polished with a README and pinned, documented repos -- [ ] You can run the full real-world loop (fork β†’ branch β†’ commit β†’ push β†’ PR β†’ review) **from memory** +# Course complete when + +- [ ] all module transition conditions are complete +- [ ] cumulative gates in [`../ASSESSMENTS.md`](../ASSESSMENTS.md) are passed +- [ ] Part A real contribution is complete +- [ ] Part B recovery practical is complete +- [ ] Part C profile presentation is complete +- [ ] you can complete the normal local/remote/PR workflow without step-by-step instructions +- [ ] you can investigate common Git problems without immediately reaching for destructive commands + +At that point the target is not β€œI memorized Git.” It is: -When both parts are done, you are genuinely **confident** with Git and GitHub β€” not just aware of it. That's the whole goal. 🫑 +> **I can inspect a repository, reason about its state, collaborate safely, and recover when I make a mistake.** \ No newline at end of file From 317a0cec1f29d0a9612a8c1c3e9863dd5998794b Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:12:39 +0600 Subject: [PATCH 15/17] Align cumulative gates with course progression --- ASSESSMENTS.md | 277 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 206 insertions(+), 71 deletions(-) diff --git a/ASSESSMENTS.md b/ASSESSMENTS.md index 639e565..61cc765 100644 --- a/ASSESSMENTS.md +++ b/ASSESSMENTS.md @@ -1,106 +1,241 @@ # Cumulative Mastery Assessments -These checks are intentionally cumulative. Do them in your separate `git-github-lab` repository. +These are practical gates, not quizzes. Perform them in your separate disposable **`git-github-lab`** repository. -Do not read the command solutions while attempting them. Use `git status`, `git diff`, `git log`, `git help`, and official documentation as needed. +You may use `git help` and official documentation unless a gate explicitly says closed-reference. Do not follow a memorized solution script. The goal is to inspect state, choose operations deliberately, and explain what happened. -## Gate A β€” Local Git Ready (after Module 1) +--- -Without copying commands: +## Gate 1 β€” Local Git Fundamentals (after Module 1) -1. Create a repository. -2. Make two files. -3. Commit only one of them. -4. Explain why the other file was excluded. -5. Modify the committed file. -6. Show the unstaged diff. -7. Stage it. -8. Show the staged diff. -9. Commit it with a useful message. -10. Add an ignore rule and prove it works. +### Practical -Pass when you can explain the working tree, staging area, and commit history while demonstrating them. +Without copying a command sequence: -## Gate B β€” Branching Ready (after Module 2) +1. create or reset a disposable practice repository +2. make two new files +3. inspect the state +4. stage only one file +5. inspect exactly what is staged +6. commit it with a useful message +7. explain why the other file was excluded +8. modify the committed file +9. show its unstaged diff +10. stage it and prove the same change moved into the staged diff +11. commit it +12. create an ignore rule and prove it works +13. show your final history -1. Start with a clean `main`. -2. Create two feature branches from the same baseline. -3. Make different commits on both. -4. Inspect the graph. -5. Merge one branch. -6. Predict whether the second merge will fast-forward, auto-merge, or conflict. -7. Perform it and explain the result. -8. Clean up merged branches safely. +### Oral check -## Gate C β€” GitHub Round Trip (after Module 3) +Explain: -Using a disposable GitHub repository: +- working tree +- staging area/index +- commit +- `HEAD` +- `git diff` vs `git diff --staged` +- why `.gitignore` is not secret-removal -1. Clone it on your computer. -2. Make and push a local commit. -3. Make a different commit through GitHub's web editor. -4. Use `fetch` first and inspect the relationship before updating your local branch. -5. Bring the remote change down. -6. Push another local change. -7. Explain `origin`, upstream tracking, fetch, pull, and push. +### Pass standard -## Gate D β€” Collaboration Ready (after Module 4) +You can create focused commits without blindly staging everything, and you can explain the state before and after each operation. -In a practice repository or with a study partner: +--- -1. Open an Issue describing a small change. -2. Create a branch for it. -3. Make focused commits. -4. Push the branch. -5. Open a Pull Request linked to the Issue. -6. Read the diff as a reviewer would. -7. Receive or simulate review feedback. -8. Update the same PR with another commit. -9. Merge it and confirm the Issue closes. +## Gate 2 β€” Branching (after Module 2) -## Gate E β€” Recovery Ready (after Module 5) +### Practical -You must demonstrate all of these without damaging important work: +1. start from a clean `main` +2. create two branches from the same baseline +3. make different commits on both branches +4. inspect the graph and identify the branch tips +5. compare branch content/history +6. merge one branch into `main` +7. predict what will happen when integrating the other branch +8. perform the integration +9. inspect the resulting graph +10. safely delete branches that are no longer needed -- unstage while preserving edits -- stash and restore work -- revert a committed change -- amend an unpublished commit -- use a soft reset and explain the resulting staged state -- deliberately displace a committed change and recover it through reflog + a recovery branch +### Oral check -Before each potentially destructive action, state what you expect to happen. +Explain: -## Final Disaster Lab (after Module 6) +- branch vs folder copy +- branch vs commit +- `HEAD` +- merge direction +- fast-forward vs divergent/three-way merge +- what `git branch -d` protects you from in common cases -Create a throwaway repository containing several meaningful commits and branches. Then intentionally create this situation: +### Pass standard -1. feature branch and `main` diverge -2. same line changes on both branches -3. merge conflict occurs -4. one local commit becomes "lost" through a deliberate reset -5. remote has a commit local does not yet have +You can reason from the graph rather than guessing what a branch or merge will do. -Recover the repository into a clean, understandable state. +--- -Required evidence: +## Gate 3 β€” Remote / GitHub Round Trip (after Module 3) + +Use a disposable GitHub repository. + +### Practical + +1. connect or clone the repository locally +2. identify `origin`, local `main`, and `origin/main` +3. make and push a local commit +4. make a different commit through GitHub's web editor +5. **fetch first** +6. inspect the graph and the commits/diff between local and remote-tracking branches +7. integrate the remote change safely +8. create one local commit while also creating a different GitHub-side commit before synchronizing +9. fetch and diagnose the resulting divergence +10. integrate it without raw force push +11. push the resolved history + +### Oral check + +Explain: + +- remote +- `origin` +- local branch vs remote-tracking branch +- upstream tracking +- fetch +- pull +- push +- why a rejected push is not an instruction to force-push + +### Pass standard + +You can complete and diagnose a local↔GitHub round trip while inspecting before integrating. + +--- + +## Gate 4 β€” Collaboration (after Module 4) + +Use a repository you control for the full lifecycle, and use a fork-based practice repository to demonstrate external contribution setup. + +### Practical + +1. show the difference between branch, clone, and fork +2. in a fork, show `origin` and `upstream` +3. in your own repo, open an Issue describing a small change and acceptance criteria +4. create a focused branch +5. inspect/stage/commit the implementation +6. push the branch and open a Pull Request linked to the Issue +7. inspect the PR diff as a reviewer +8. receive or simulate review feedback +9. update the **same PR** with another commit +10. merge it using an appropriate merge method +11. verify the linked Issue state + +### Oral check + +Explain what you would inspect before opening a PR to a project you do not own: + +- contribution guide +- existing Issues/PRs +- assignment/maintainer expectations +- validation requirements +- project scope + +### Pass standard + +You can use GitHub as a collaboration system rather than merely as file hosting. + +--- + +## Gate 5 β€” Recovery (after Module 5) + +Every destructive experiment must happen only in disposable work. + +### Practical + +Demonstrate all of these: + +1. unstage a change while preserving the edit +2. stash and restore work +3. deliberately discard a throwaway uncommitted edit and explain why Git may not recover it +4. amend an unpublished commit +5. soft-reset an unpublished commit and explain the staged result +6. revert a committed change and show that history is preserved +7. deliberately displace a **committed** change with a controlled reset +8. find that commit in reflog +9. recover it using a new recovery branch + +### Safety narration + +Before each risky action, state: + +- what can change in the working tree +- what can change in the index +- what can happen to branch history +- whether another person could already depend on the commit + +### Pass standard + +You choose recovery operations based on the state/problem instead of treating undo commands as interchangeable. + +--- + +## Gate 6 β€” Real-World Git / Disaster Lab (after Module 6) + +Create a throwaway repository with several meaningful commits and branches. + +Then intentionally construct this situation: + +1. `main` and a feature branch diverge +2. both modify the same line differently +3. a merge conflict occurs +4. resolve the conflict and inspect the merge graph +5. create a local commit and a different remote commit to produce local/remote divergence +6. fetch and diagnose it before integration +7. integrate it without raw force push +8. create another committed change +9. deliberately displace that commit in the disposable repo +10. recover it with reflog + a recovery branch +11. create an annotated version tag and inspect it +12. inspect a basic GitHub Actions workflow and identify trigger/jobs/steps + +### Required evidence + +Capture or record the relevant output from: ```bash git status +git branch -vv +git remote -v git log --oneline --graph --decorate --all git reflog ``` -At the end, write a short incident report: +### Incident report + +Write a short report: + +- what state you intentionally created +- what evidence told you what was happening +- what you predicted before each recovery step +- which operations preserved history +- which operations rewrote/moved history +- why your chosen recovery was safer than tempting alternatives +- what you would do differently in an important/shared repository + +### Pass standard + +You can enter an unfamiliar-looking Git problem, inspect first, form a reasonable model, recover deliberately, and verify the result. + +--- + +# Graduation standard + +Passing all six gates means you are ready for the capstone. -- what happened -- what Git state you observed -- which recovery actions you chose -- why those actions were safer than alternatives -- what you would do differently in an important repository +You are **not** expected to remember every Git flag. -## Graduation standard +You are expected to have this response to confusion: -You are not finished because you remember every flag. +> **inspect β†’ model the current state β†’ predict β†’ choose the least destructive appropriate operation β†’ verify** -You are finished when an unfamiliar Git problem causes you to **inspect first**, form a mental model of the repository state, choose a deliberate operation, and verify the result afterward. +That is the independence target of this course. \ No newline at end of file From 624929e7604ceea237797db8207408f8085f27de Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:12:54 +0600 Subject: [PATCH 16/17] Add recovery mastery gate --- Module_5_Fixing_Mistakes/Module_5_Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Module_5_Fixing_Mistakes/Module_5_Guide.md b/Module_5_Fixing_Mistakes/Module_5_Guide.md index 315ca6b..e70b6b0 100644 --- a/Module_5_Fixing_Mistakes/Module_5_Guide.md +++ b/Module_5_Fixing_Mistakes/Module_5_Guide.md @@ -191,4 +191,5 @@ From memory, recover a deliberately displaced **committed** change using reflog - [ ] You can amend/reset your own unpublished history deliberately - [ ] You can use revert to preserve shared history - [ ] You can recover a displaced commit with reflog + a recovery branch -- [ ] **All Transition Conditions passed β†’ start Module 6** + +Then complete **Gate 5 β€” Recovery** in [`../ASSESSMENTS.md`](../ASSESSMENTS.md). Pass it before starting Module 6. \ No newline at end of file From 928b882c8ec56f2cc551df82361a2b307cbe6ddc Mon Sep 17 00:00:00 2001 From: adhamcodes <219492688+adhamcodes@users.noreply.github.com> Date: Sun, 30 Aug 2026 07:13:33 +0600 Subject: [PATCH 17/17] Connect final module to disaster gate --- Module_6_Real_World/Module_6_Guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Module_6_Real_World/Module_6_Guide.md b/Module_6_Real_World/Module_6_Guide.md index c000f80..1d689fa 100644 --- a/Module_6_Real_World/Module_6_Guide.md +++ b/Module_6_Real_World/Module_6_Guide.md @@ -205,4 +205,5 @@ You can explain what CI/Actions does, locate a workflow, identify its trigger/jo - [ ] You can rebase your own branch and explain the shared-history boundary - [ ] You can tag and release a version deliberately - [ ] You can read a basic GitHub Actions workflow -- [ ] **All Transition Conditions passed β†’ start the Capstone** + +Then complete **Gate 6 β€” Real-World Git / Disaster Lab** in [`../ASSESSMENTS.md`](../ASSESSMENTS.md). Pass it before beginning the capstone. \ No newline at end of file