From 5492f17a5a8d50d36cb496f74cdcc5b8db653812 Mon Sep 17 00:00:00 2001 From: Bjarke Sporring Date: Mon, 12 Jan 2026 08:42:20 +0100 Subject: [PATCH] fix: cleanup README and focus on windows --- 01-essentials/08-multiplayer/README.md | 12 +- 02-advanced/04-bisect/README.md | 24 +- INSTALLATION.md | 303 +++++++++++++++++++++++++ README.md | 107 ++++----- 4 files changed, 365 insertions(+), 81 deletions(-) create mode 100644 INSTALLATION.md diff --git a/01-essentials/08-multiplayer/README.md b/01-essentials/08-multiplayer/README.md index bd1cad7..61ed36f 100644 --- 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 diff --git a/02-advanced/04-bisect/README.md b/02-advanced/04-bisect/README.md index e82b1c6..10870b9 100644 --- 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 diff --git a/INSTALLATION.md b/INSTALLATION.md new file mode 100644 index 0000000..d5c5589 --- /dev/null +++ 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! diff --git a/README.md b/README.md index 957191d..1732ebf 100644 --- 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:** -```powershell -git --version -``` +**Quick Check:** -If you see a version number (e.g., "git version 2.34.1"), you're all set! +You need the following software installed: -If not, download and install from: https://git-scm.com/downloads +- **Git 2.23+** - Version control system + ```powershell + git --version + ``` -**Configure Git (Required - First Time Only):** +- **PowerShell 7+** + ```powershell + pwsh --version + ``` -Before making your first commit, tell Git who you are: +- **Python 3.6+** (for Module 08 only) + ```powershell + python --version + ``` + +**First-Time Git Configuration:** + +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 ```