git-workshop/INSTALLATION.md

# Installation Guide for Windows 11

This guide will help you install everything needed for the Git Workshop on Windows 11.

## Quick Start (Automated Installation)

**Easiest option:** Run our one-shot installation script that automatically installs all required tools using winget.

1. Open **PowerShell** or **Windows Terminal**
2. Navigate to the git-workshop directory
3. Run the installation script:

```powershell
.\install-prerequisites.ps1
```

The script will:
- Check if tools are already installed
- Install PowerShell 7, Git 2.23+, and Visual Studio Code
- Prompt you for optional tools (Python 3.12, Windows Terminal)
- Show clear progress and verify each installation
- Display Git configuration instructions when complete

**If you prefer manual installation**, continue with the detailed steps below.

---

## 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

## Manual 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!