From dc94520b2aef3e8f878e45f96b20dd07e6de85fc Mon Sep 17 00:00:00 2001 From: Bjarke Sporring Date: Mon, 5 Jan 2026 12:47:33 +0100 Subject: [PATCH] feat: add guidance for beginners to get started --- README.md | 105 +++++++++++++++++++++++++++++++++++-- module-01-basics/README.md | 35 ++++++++++++- 2 files changed, 135 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9ce1f2d..85d1038 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,94 @@ Each module is a self-contained challenge that teaches specific git concepts: 5. Run `./verify.ps1` to check if you've solved it correctly 6. Move to the next module -**Quick Reference**: See [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) for a comprehensive list of all Git commands covered in this workshop. +**Quick Reference**: See [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) for a comprehensive list of all Git commands covered in this workshop. Don't worry about memorizing everything - use this as a reference when you need to look up command syntax! + +## Running PowerShell Scripts + +Each module includes setup, verification, and reset scripts. Here's how to run them: + +### Windows + +If you encounter an "execution policy" error when running scripts, open PowerShell as Administrator and run: + +```powershell +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +``` + +Then run scripts using: +```powershell +.\setup.ps1 +``` + +### macOS/Linux + +First, make sure scripts are executable (only needed once): +```bash +chmod +x module-*/setup.ps1 module-*/verify.ps1 module-*/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 installed and configured -- PowerShell (Windows PowerShell 5.1+ or PowerShell Core 7+) -- Basic command line knowledge +### Git + +You need Git version 2.23 or later (for `git switch` and `git restore` commands). + +**Check if Git is installed:** +```powershell +git --version +``` + +If you see a version number (e.g., "git version 2.34.1"), you're all set! + +If not, download and install from: https://git-scm.com/downloads + +**Configure Git (Required - First Time Only):** + +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. 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 +``` + +### Basic Command Line Knowledge + +You should know how to: +- Navigate directories (`cd`, `ls` or `dir`) +- See your current location (`pwd`) +- Read text files (`cat` or `type`) + +Don't worry if you're not an expert - we'll guide you through each step! ## Optional: Install Glow for Pretty Markdown @@ -66,6 +147,22 @@ After installation, read markdown files with: Without glow, you can still read markdown files with any text editor or `cat README.md`. +## Common Git Terms + +New to Git? Here are the key terms you'll encounter: + +- **Repository (or "repo")**: A project folder tracked by Git, containing your files and their complete history +- **Commit**: A snapshot of your project at a specific point in time (like a save point in a video game) +- **Staging Area (or "Index")**: A preparation area where you select which changes to include in your next commit +- **Working Directory**: The actual files you see and edit on your computer +- **Branch**: An independent line of development (like a parallel universe for your code) +- **HEAD**: A pointer showing which commit you're currently working from +- **main/master**: The primary branch in a repository (main is the modern convention) +- **Merge**: Combining changes from different branches +- **Remote**: A version of your repository hosted elsewhere (like GitHub) + +Don't worry if these don't make sense yet - you'll learn them hands-on as you progress! + ## Getting Started Start with Module 01: diff --git a/module-01-basics/README.md b/module-01-basics/README.md index 77288ef..f4055d8 100644 --- a/module-01-basics/README.md +++ b/module-01-basics/README.md @@ -59,14 +59,47 @@ git log # View commit history ### Verification -Once you think you've completed the challenge, run: +Once you think you've completed the challenge, run the verification script. + +**Important:** Run this from the **module directory**, not the challenge directory. ```powershell +# If you're in the challenge directory, go back up: +cd .. + +# Then verify: .\verify.ps1 ``` This will check if you've successfully completed all the steps. +### Troubleshooting + +**Error: "fatal: unable to auto-detect email address"** + +This means Git doesn't know who you are yet. You need to configure your name and email: + +```powershell +git config user.name "Your Name" +git config user.email "your.email@example.com" +``` + +Then try your commit again. For more details, see the "Requirements" section in the main README.md. + +**Error: "Not a git repository"** + +Make sure you ran `git init` in the challenge directory. This creates a hidden `.git` folder that tracks your project. + +**Can't find the challenge directory?** + +Make sure you ran `.\setup.ps1` first from the module directory. This creates the `challenge/` folder. + +**Where am I?** + +Use `pwd` (Print Working Directory) to see your current location: +- If you're in something like `.../module-01-basics/challenge`, you're in the challenge directory +- If you're in something like `.../module-01-basics`, you're in the module directory + ### Need to Start Over? If you want to reset the challenge and start fresh, run: