fix: cleanup README and focus on windows

2026-01-12 08:42:20 +01:00
parent 5f78245734
commit 5492f17a5a
4 changed files with 365 additions and 81 deletions
--- a/01-essentials/08-multiplayer/README.md
+++ b/01-essentials/08-multiplayer/README.md
@@ -1372,12 +1372,12 @@ You've completed this module when you can check off ALL of these:

 Continue your Git journey with advanced techniques:

- **02_advanced/01-rebasing**: Learn to rebase instead of merge for cleaner history
- **02_advanced/02-interactive-rebase**: Clean up messy commits before submitting PRs
- **02_advanced/03-worktrees**: Work on multiple branches simultaneously
- **02_advanced/04-bisect**: Find bugs using binary search through commit history
- **02_advanced/05-blame**: Investigate who changed what and when
- **02_advanced/06-merge-strategies**: Master different merge strategies and when to use them
+- **02-advanced/01-rebasing**: Learn to rebase instead of merge for cleaner history
+- **02-advanced/02-interactive-rebase**: Clean up messy commits before submitting PRs
+- **02-advanced/03-worktrees**: Work on multiple branches simultaneously
+- **02-advanced/04-bisect**: Find bugs using binary search through commit history
+- **02-advanced/05-blame**: Investigate who changed what and when
+- **02-advanced/06-merge-strategies**: Master different merge strategies and when to use them

 ### Practice More

--- a/02-advanced/04-bisect/README.md
+++ b/02-advanced/04-bisect/README.md
@@ -74,7 +74,7 @@ Use bisect when:

 ## Useful Commands

-```bash
+```powershell
 # Start bisect session
 git bisect start

@@ -112,7 +112,7 @@ git bisect log

 Run the verification script to check your solution:

-```bash
+```powershell
 .\verify.ps1
 ```

@@ -152,7 +152,7 @@ The verification will check that:
 ## Manual vs Automated Bisect

 ### Manual Bisect
-```bash
+```powershell
 git bisect start
 git bisect bad
 git bisect good HEAD~20
@@ -165,7 +165,7 @@ git bisect reset
 ```

 ### Automated Bisect
-```bash
+```powershell
 git bisect start
 git bisect bad
 git bisect good HEAD~20
@@ -182,22 +182,28 @@ The test script should exit with:
 ## Bisect Workflow Example

 ### Finding a Performance Regression
-```bash
+```powershell
 # App is slow now, was fast 50 commits ago
 git bisect start
 git bisect bad
 git bisect good HEAD~50

 # Create test script
-echo '#!/bin/bash\ntime npm start | grep "Started in"' > test.sh
-chmod +x test.sh
+@'
+$output = npm start 2>&1 | Select-String "Started in"
+if ($output -match "Started in (\d+)") {
+  if ([int]$Matches[1] -gt 5000) { exit 1 } # Slow
+  else { exit 0 } # Fast
+}
+exit 1
+'@ | Out-File -FilePath test.ps1

-git bisect run ./test.sh
+git bisect run pwsh test.ps1
 # Git finds the commit that made it slow
 ```

 ### Finding When a Feature Broke
-```bash
+```powershell
 git bisect start
 git bisect bad
 git bisect good v1.0.0  # Last known good version
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@@ -0,0 +1,303 @@
+# Installation Guide for Windows 11
+
+This guide will help you install everything needed for the Git Workshop on Windows 11.
+
+## Prerequisites
+
+You'll need administrator access to install software on your Windows 11 machine.
+
+## What You'll Install
+
+1. **PowerShell 7** - Modern cross-platform PowerShell (replaces the older Windows PowerShell 5.1)
+2. **Git** - Version control system (2.23 or later)
+3. **Visual Studio Code** - Modern code editor with excellent Git integration
+
+## Installation Steps
+
+### 1. Install PowerShell 7
+
+PowerShell 7 is the modern, cross-platform version of PowerShell. Windows 11 comes with PowerShell 5.1, but we recommend PowerShell 7 for the best experience.
+
+**Option A: Using winget (Recommended)**
+
+Open **Windows Terminal** or **Command Prompt** and run:
+
+```powershell
+winget install --id Microsoft.PowerShell --source winget
+```
+
+**Option B: Manual Download**
+
+1. Visit https://github.com/PowerShell/PowerShell/releases/latest
+2. Download the file ending in `-win-x64.msi` (e.g., `PowerShell-7.4.1-win-x64.msi`)
+3. Run the installer
+4. Accept all defaults
+
+**Verify Installation:**
+
+Open a new terminal and run:
+
+```powershell
+pwsh --version
+```
+
+You should see version 7.x.x or higher.
+
+**Important:** After installing PowerShell 7, use it instead of the older "Windows PowerShell 5.1". Look for "PowerShell 7" in your Start menu or Windows Terminal.
+
+### 2. Install Git
+
+Git is the version control system you'll learn in this workshop. You need version 2.23 or later.
+
+**Option A: Using winget (Recommended)**
+
+```powershell
+winget install --id Git.Git -e --source winget
+```
+
+**Option B: Manual Download**
+
+1. Visit https://git-scm.com/downloads
+2. Click "Windows"
+3. Download the 64-bit installer
+4. Run the installer with these recommended settings:
+   - **Default editor**: Choose "Visual Studio Code" (we'll install it next)
+   - **PATH environment**: Select "Git from the command line and also from 3rd-party software"
+   - **Line ending conversions**: Choose "Checkout Windows-style, commit Unix-style line endings"
+   - **Terminal emulator**: Choose "Use Windows' default console window"
+   - All other settings: Accept defaults
+
+**Verify Installation:**
+
+Open a **new** PowerShell window and run:
+
+```powershell
+git --version
+```
+
+You should see version 2.23 or higher (e.g., `git version 2.43.0`).
+
+### 3. Install Visual Studio Code
+
+VS Code is a free, powerful code editor with excellent Git integration.
+
+**Option A: Using winget (Recommended)**
+
+```powershell
+winget install --id Microsoft.VisualStudioCode --source winget
+```
+
+**Option B: Manual Download**
+
+1. Visit https://code.visualstudio.com/
+2. Click "Download for Windows"
+3. Run the installer
+4. During installation, check these options:
+   - ✅ Add "Open with Code" action to Windows Explorer file context menu
+   - ✅ Add "Open with Code" action to Windows Explorer directory context menu
+   - ✅ Register Code as an editor for supported file types
+   - ✅ Add to PATH
+
+**Verify Installation:**
+
+```powershell
+code --version
+```
+
+You should see version information.
+
+**Recommended VS Code Extensions:**
+
+Open VS Code and install these extensions for the best Git experience:
+
+1. **GitLens** - Supercharge Git capabilities
+   - Press `Ctrl+Shift+X` to open Extensions
+   - Search for "GitLens"
+   - Click Install
+
+2. **Git Graph** - View Git history visually
+   - Search for "Git Graph"
+   - Click Install
+
+3. **PowerShell** - Better PowerShell support
+   - Search for "PowerShell"
+   - Install the one from Microsoft
+
+## Configure Git
+
+Before making your first commit, tell Git who you are:
+
+```powershell
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+```
+
+**Verify your configuration:**
+
+```powershell
+git config --global user.name
+git config --global user.email
+```
+
+You should see your name and email printed.
+
+**Optional: Set VS Code as Git's Default Editor**
+
+If you installed Git before VS Code, configure Git to use VS Code:
+
+```powershell
+git config --global core.editor "code --wait"
+```
+
+## PowerShell Execution Policy
+
+When running PowerShell scripts (`.ps1` files) in this workshop, you might encounter an error about execution policies.
+
+**If you see an error like "script cannot be loaded because running scripts is disabled":**
+
+Open **PowerShell 7 as Administrator** and run:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+This allows you to run local scripts while maintaining security for downloaded scripts.
+
+## Running Scripts in the Workshop
+
+After installation, you can run workshop scripts using:
+
+```powershell
+.\setup.ps1
+.\verify.ps1
+.\reset.ps1
+```
+
+**Example workflow:**
+
+```powershell
+# Navigate to a module
+cd 01-essentials\01-basics
+
+# Run the setup script
+.\setup.ps1
+
+# Complete the challenge using Git commands
+# ...
+
+# Verify your solution
+.\verify.ps1
+```
+
+## Optional: Python (for Module 08 only)
+
+Module 08 (Multiplayer Git) uses Python for "The Great Print Project". You only need this for that specific module.
+
+**Install Python 3.12:**
+
+```powershell
+winget install --id Python.Python.3.12 --source winget
+```
+
+**Verify installation:**
+
+```powershell
+python --version
+```
+
+You should see Python 3.12.x or higher.
+
+## Optional: Windows Terminal (Highly Recommended)
+
+Windows Terminal provides a modern terminal experience with tabs, better colors, and PowerShell 7 integration.
+
+**Install:**
+
+```powershell
+winget install --id Microsoft.WindowsTerminal --source winget
+```
+
+Or install from the **Microsoft Store** (search for "Windows Terminal").
+
+**After installation:**
+- Press `Win+X` and select "Windows Terminal"
+- Or search "Terminal" in the Start menu
+- PowerShell 7 should be the default profile
+
+## Verify Complete Installation
+
+Run these commands to verify everything is installed correctly:
+
+```powershell
+# PowerShell version (should be 7.x.x)
+pwsh --version
+
+# Git version (should be 2.23 or higher)
+git --version
+
+# VS Code version
+code --version
+
+# Git configuration
+git config --global user.name
+git config --global user.email
+
+# Optional: Python (for Module 08)
+python --version
+```
+
+## Troubleshooting
+
+### Git command not found
+
+If `git --version` doesn't work after installation:
+1. Close and reopen your terminal (Git needs a new terminal to update PATH)
+2. Restart your computer if the problem persists
+
+### VS Code command not found
+
+If `code --version` doesn't work:
+1. Ensure you checked "Add to PATH" during installation
+2. Close and reopen your terminal
+3. If still not working, reinstall VS Code with the PATH option enabled
+
+### PowerShell execution policy errors
+
+If you can't run `.ps1` scripts:
+1. Open PowerShell 7 **as Administrator**
+2. Run: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
+3. Close admin PowerShell and try again in a regular PowerShell window
+
+### winget command not found
+
+If `winget` doesn't work:
+1. Update Windows 11 to the latest version (Settings → Windows Update)
+2. Install "App Installer" from the Microsoft Store
+3. Restart your computer
+
+## You're Ready!
+
+Once all verification commands work, you're ready to start the workshop!
+
+```powershell
+# Clone or download the git-workshop repository
+# Navigate to it
+cd path\to\git-workshop
+
+# Start with Module 01
+cd 01-essentials\01-basics
+
+# Read the instructions
+code README.md
+
+# Run setup and begin!
+.\setup.ps1
+```
+
+## Next Steps
+
+- Read the main [README.md](README.md) for workshop overview
+- Check [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) for Git command reference
+- Start with Module 01: `01-essentials\01-basics`
+
+Happy learning!
--- a/README.md
+++ b/README.md
@@ -36,7 +36,7 @@ Advanced Git workflows for power users:

 ### For Local Modules (01-08 in Essentials, all Advanced modules)

-1. Navigate to a module directory (e.g., `01_essentials/01-basics`)
+1. Navigate to a module directory (e.g., `01-essentials/01-basics`)
 2. Read the `README.md` to understand the challenge
 3. Run `./setup.ps1` to create the challenge environment
 4. Complete the challenge using git commands
@@ -49,20 +49,18 @@ Advanced Git workflows for power users:

 **This module is different!** It uses a real Git server for authentic collaboration:

-1. Navigate to `01_essentials/08-multiplayer`
+1. Navigate to `01-essentials/08-multiplayer`
 2. Read the `README.md` for complete instructions
 3. **No setup script** - you'll clone from https://git.frod.dk/multiplayer
 4. Work with a partner on shared branches
 5. Experience real merge conflicts and pull requests
 6. **No verify script** - success is visual (your code appears in the final output)

-**Facilitators**: See `01_essentials/08-multiplayer/FACILITATOR-SETUP.md` for server setup and workshop guidance.
+**Facilitators**: See `01-essentials/08-multiplayer/FACILITATOR-SETUP.md` for server setup and workshop guidance.

 ## Running PowerShell Scripts

-Most modules include setup, verification, and reset scripts. Here's how to run them:
-
-### Windows
+Most modules include setup, verification, and reset scripts.

 If you encounter an "execution policy" error when running scripts, open PowerShell as Administrator and run:

@@ -73,76 +71,50 @@ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 Then run scripts using:
 ```powershell
 .\setup.ps1
+.\verify.ps1
+.\reset.ps1
 ```

-### macOS/Linux
-
-First, make sure scripts are executable (only needed once):
-```bash
-chmod +x 01_essentials/*/setup.ps1 01_essentials/*/verify.ps1 01_essentials/*/reset.ps1
-chmod +x 02_advanced/*/setup.ps1 02_advanced/*/verify.ps1 02_advanced/*/reset.ps1
-```
-
-Then run scripts using:
-```bash
-./setup.ps1
-```
-
-Or explicitly with PowerShell:
-```bash
-pwsh setup.ps1
-```
-
-**Note:** All examples in this workshop use Windows syntax (`.\script.ps1`). macOS/Linux users should use `./script.ps1` instead.
-
 ## Requirements

-### Git
+### Installation

-You need Git version 2.23 or later (for `git switch` and `git restore` commands).
+**Windows 11 Users:** See [INSTALLATION.md](INSTALLATION.md) for complete step-by-step installation instructions including PowerShell 7, Git, and Visual Studio Code.

-**Check if Git is installed:**
+**Quick Check:**
+
+You need the following software installed:
+
+- **Git 2.23+** - Version control system
  ```powershell
  git --version
  ```

-If you see a version number (e.g., "git version 2.34.1"), you're all set!
+- **PowerShell 7+**
+  ```powershell
+  pwsh --version
+  ```

-If not, download and install from: https://git-scm.com/downloads
+- **Python 3.6+** (for Module 08 only)
+  ```powershell
+  python --version
+  ```

-**Configure Git (Required - First Time Only):**
+**First-Time Git Configuration:**

-Before making your first commit, tell Git who you are:
+Before making your first commit, configure Git with your identity:

 ```powershell
 git config --global user.name "Your Name"
 git config --global user.email "your.email@example.com"
 ```

-**Verify your configuration:**
+Verify your configuration:
 ```powershell
 git config --global user.name
 git config --global user.email
 ```

-You should see your name and email printed. This is required to make commits in Git.
-
-### PowerShell
-
- **Windows**: PowerShell 5.1+ (already included in Windows 10/11)
- **macOS/Linux**: Install PowerShell Core 7+ from https://github.com/PowerShell/PowerShell
-
-**Check PowerShell version:**
-```powershell
-$PSVersionTable.PSVersion
-```
-
-### Python (for Module 08 only)
-
-Module 08 (Multiplayer Git) uses Python:
- **Python 3.6+** required to run the Great Print Project
- Check: `python --version` or `python3 --version`
-
 ### Basic Command Line Knowledge

 You should know how to:
@@ -163,11 +135,7 @@ This workshop includes many markdown files with instructions. You can install `g
 After installation, read markdown files with:

 ```powershell
-# Windows
 .\bin\glow.exe README.md
-
-# macOS/Linux
-./bin/glow README.md
 ```

 **Pro tip**: Use `glow -p` for pager mode on longer files!
@@ -194,10 +162,12 @@ Don't worry if these don't make sense yet - you'll learn them hands-on as you pr

 ## Getting Started

-Start with Essentials Module 01:
+**First time?** Make sure you have Git and PowerShell installed - see [INSTALLATION.md](INSTALLATION.md) for Windows 11 setup instructions.
+
+Once installed, start with Essentials Module 01:

 ```powershell
-cd 01_essentials/01-basics
+cd 01-essentials\01-basics
 .\setup.ps1
 ```

@@ -345,7 +315,7 @@ Run your own Git server with Gitea using Docker and Cloudflare Tunnel:

 **Setup:**
 1. See [GITEA-SETUP.md](GITEA-SETUP.md) for complete Gitea + Docker + Cloudflare Tunnel instructions
-2. See `01_essentials/08-multiplayer/FACILITATOR-SETUP.md` for detailed workshop preparation:
+2. See `01-essentials/08-multiplayer/FACILITATOR-SETUP.md` for detailed workshop preparation:
   - Creating student accounts
   - Setting up The Great Print Project repository
   - Pairing students
@@ -369,13 +339,14 @@ You can also use existing cloud Git platforms:
 ```
 git-workshop/
 ├── README.md                          # This file
+├── INSTALLATION.md                    # Windows 11 installation guide (PowerShell 7, Git, VS Code)
 ├── GIT-CHEATSHEET.md                  # Quick reference for all Git commands
 ├── WORKSHOP-AGENDA.md                 # Facilitator guide for running workshops
 ├── PRESENTATION-OUTLINE.md            # Slide deck outline
 ├── GITEA-SETUP.md                     # Self-hosted Git server setup
 ├── install-glow.ps1                   # Install glow markdown renderer
 │
-├── 01_essentials/                     # Core Git skills (8 modules)
+├── 01-essentials/                     # Core Git skills (8 modules)
 │   ├── 01-basics/                     # Initialize, commit, status
 │   ├── 02-history/                    # Log, diff, show
 │   ├── 03-branching-and-merging/      # Branches, merging, conflicts (checkpoint-based)
@@ -387,7 +358,7 @@ git-workshop/
 │       ├── README.md                  # Student guide
 │       └── FACILITATOR-SETUP.md       # Server setup guide
 │
-└── 02_advanced/                       # Professional techniques (6 modules)
+└── 02-advanced/                       # Professional techniques (6 modules)
    ├── 01-rebasing/                   # Linear history with rebase
    ├── 02-interactive-rebase/         # Clean up commits
    ├── 03-worktrees/                  # Multiple branches simultaneously
@@ -468,10 +439,14 @@ This workshop is provided as-is for educational purposes.

 ---

-**Ready to master Git? Start with Essentials Module 01 and begin your journey!**
+**Ready to master Git?**
+
+First-time setup (Windows 11): See [INSTALLATION.md](INSTALLATION.md)
+
+Then start with Essentials Module 01 and begin your journey!

 ```powershell
-cd 01_essentials/01-basics
+cd 01-essentials\01-basics
 .\setup.ps1
 ```