diff --git a/README.md b/README.md index 85d1038..7c32828 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,43 @@ # Git Workshop -A comprehensive, hands-on Git workshop with 13 progressive modules covering everything from basic commits to advanced debugging techniques. Each module presents a real-world scenario that you must solve using Git commands, with automated verification to confirm your solution. +A comprehensive, hands-on Git workshop with 15 progressive modules covering everything from basic commits to advanced debugging techniques and real-world collaboration. Each module presents a real-world scenario that you must solve using Git commands, with automated verification to confirm your solution. -Perfect for developers who want to move beyond basic Git usage and master professional workflows including rebasing, conflict resolution, bisecting, worktrees, and more. +Perfect for developers who want to move beyond basic Git usage and master professional workflows including rebasing, conflict resolution, collaboration, and advanced Git techniques. ## Workshop Structure -Each module is a self-contained challenge that teaches specific git concepts: +The workshop is organized into two tracks: -### Beginner Level -- **Module 01**: Git Basics - Initialize repositories, stage changes, make commits -- **Module 02**: Viewing History - Use git log and git diff to explore project history -- **Module 03**: Branching Basics - Create, switch, and manage branches +### 01 Essentials - Core Git Skills (9 modules) -### Intermediate Level -- **Module 04**: Merging - Combine branches with fast-forward and three-way merges -- **Module 05**: Merge Conflicts - Identify, understand, and resolve merge conflicts -- **Module 06**: Rebasing - Rebase branches to create linear history -- **Module 07**: Interactive Rebase - Clean up commit history with reset and recommit -- **Module 08**: Cherry-Pick - Apply specific commits from one branch to another +Master fundamental Git concepts and collaborative workflows: -### Advanced Level -- **Module 09**: Reset vs Revert - Understand when to rewrite history vs create new commits -- **Module 10**: Stash - Temporarily save work without committing -- **Module 11**: Working with Remotes - Clone, push, pull, and fetch from remote repositories -- **Module 12**: Worktrees - Work on multiple branches simultaneously -- **Module 13**: Bisect - Use binary search to find bugs in commit history +- **Module 01: Git Basics** - Initialize repositories, stage changes, make commits +- **Module 02: Viewing History** - Use git log and git diff to explore project history +- **Module 03: Branching Basics** - Create, switch, and manage branches +- **Module 04: Merging** - Combine branches and understand merge workflows +- **Module 05: Merge Conflicts** - Identify, understand, and resolve merge conflicts step-by-step +- **Module 06: Cherry-Pick** - Apply specific commits from one branch to another +- **Module 07: Reset vs Revert** - Understand when to rewrite history vs create new commits +- **Module 08: Stash** - Temporarily save work without committing +- **Module 09: Multiplayer Git** - **The Great Print Project** - Real cloud-based collaboration with teammates + +### 02 Advanced - Professional Techniques (6 modules) + +Advanced Git workflows for power users: + +- **Module 01: Rebasing** - Rebase branches to create linear history +- **Module 02: Interactive Rebase** - Clean up commit history before submitting pull requests +- **Module 03: Worktrees** - Work on multiple branches simultaneously +- **Module 04: Bisect** - Use binary search to find bug-introducing commits +- **Module 05: Blame** - Code archaeology - investigate who changed what and when +- **Module 06: Merge Strategies** - Master fast-forward vs three-way merges and when to use each ## How to Use This Workshop -1. Navigate to a module directory (e.g., `module-01-basics`) +### For Local Modules (01-08 in Essentials, all Advanced modules) + +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 @@ -38,9 +46,22 @@ Each module is a self-contained challenge that teaches specific git concepts: **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! +### For Module 09: Multiplayer Git + +**This module is different!** It uses a real Git server for authentic collaboration: + +1. Navigate to `01_essentials/09-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/09-multiplayer/FACILITATOR-SETUP.md` for server setup and workshop guidance. + ## Running PowerShell Scripts -Each module includes setup, verification, and reset scripts. Here's how to run them: +Most modules include setup, verification, and reset scripts. Here's how to run them: ### Windows @@ -59,7 +80,8 @@ Then run scripts using: First, make sure scripts are executable (only needed once): ```bash -chmod +x module-*/setup.ps1 module-*/verify.ps1 module-*/reset.ps1 +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: @@ -116,6 +138,12 @@ You should see your name and email printed. This is required to make commits in $PSVersionTable.PSVersion ``` +### Python (for Module 09 only) + +Module 09 (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: @@ -159,16 +187,18 @@ New to Git? Here are the key terms you'll encounter: - **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) +- **Remote**: A version of your repository hosted elsewhere (like GitHub, GitLab, or Gitea) +- **Pull Request (PR)**: A request to merge your changes into another branch (used for code review) +- **Conflict**: When Git can't automatically merge changes because both versions modified the same lines 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: +Start with Essentials Module 01: ```powershell -cd module-01-basics +cd 01_essentials/01-basics .\setup.ps1 ``` @@ -177,54 +207,98 @@ Follow the instructions in each module's README.md file. ## What Makes This Workshop Different - **Hands-On Practice**: Each module creates a real Git scenario you must solve -- **Automated Verification**: Scripts check your solution instantly +- **Automated Verification**: Scripts check your solution instantly (modules 01-08) - **Progressive Difficulty**: Builds from basics to advanced Git techniques -- **Reset Anytime**: Each module includes a reset script for a fresh start +- **Reset Anytime**: Each local module includes a reset script for a fresh start - **Self-Paced**: Learn at your own speed with detailed README guides -- **No Internet Required**: All modules work offline with local repositories +- **Real Collaboration**: Module 09 uses an actual Git server for authentic teamwork +- **Comprehensive Coverage**: From `git init` to advanced rebasing and bisecting ## Learning Path The modules are designed to build on each other: -1. **Start Here** (Modules 1-3): Core Git fundamentals everyone needs -2. **Collaboration** (Modules 4-5): Working with branches and resolving conflicts -3. **History Management** (Modules 6-8): Rewriting and organizing commits -4. **Advanced Workflows** (Modules 9-11): Professional Git techniques -5. **Power User** (Modules 12-13): Advanced tools for productivity and debugging +### Recommended Progression + +**Phase 1: Core Fundamentals (Essentials 01-03)** +- Git Basics, History, Branching +- **Goal**: Understand commits and branches + +**Phase 2: Collaboration Basics (Essentials 04-05)** +- Merging, Merge Conflicts +- **Goal**: Work with multiple branches + +**Phase 3: Workflow Tools (Essentials 06-08)** +- Cherry-Pick, Reset vs Revert, Stash +- **Goal**: Manage your work effectively + +**Phase 4: Real Collaboration (Essentials 09)** +- **Multiplayer Git - The Great Print Project** +- **Goal**: Apply all skills with real teammates on a cloud server +- **Note**: This is a capstone module - bring everything together! + +**Phase 5: Advanced Techniques (Advanced 01-06)** +- Rebasing, Interactive Rebase, Worktrees, Bisect, Blame, Merge Strategies +- **Goal**: Master professional Git workflows +- **When**: After completing Essentials and feeling confident + +### Alternative Paths + +**Fast Track (1 day workshop):** +- Essentials 01-05 + Essentials 09 (Multiplayer) + +**Solo Learner:** +- Complete Essentials 01-08, skip 09 (requires partners and server) +- Or complete all Advanced modules for deep mastery + +**Team Workshop:** +- Essentials 01-05 then jump to 09 (Multiplayer) for collaborative practice ## Tips for Success -- Don't skip modules - each builds on previous concepts -- Read the README.md thoroughly before starting each challenge -- Keep [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) open as a quick reference -- Experiment freely - you can always run `./reset.ps1` to start over -- Use `git log --oneline --graph --all` frequently to visualize repository state -- If stuck, check the Key Concepts section in the module's README -- Consider installing glow for better markdown reading experience +- **Don't skip modules** - each builds on previous concepts +- **Read the README.md thoroughly** before starting each challenge +- **Keep [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) open** as a quick reference +- **Experiment freely** - you can always run `./reset.ps1` to start over +- **Use `git log --oneline --graph --all`** frequently to visualize repository state +- **If stuck**, check the Key Concepts section in the module's README +- **Consider installing glow** for better markdown reading experience +- **For Module 09**, work with a partner - collaboration is the point! ## Skills You'll Master By completing this workshop, you'll be able to: +### From Essentials Track: - ✅ Create and manage Git repositories with confidence - ✅ Navigate project history and understand what changed when - ✅ Use branches effectively for parallel development - ✅ Merge branches and resolve conflicts like a pro -- ✅ Rebase to maintain clean, linear history -- ✅ Clean up messy commits before submitting pull requests -- ✅ Cherry-pick specific commits across branches +- ✅ Apply specific commits with cherry-pick - ✅ Choose correctly between reset and revert - ✅ Use stash to manage work-in-progress without commits -- ✅ Collaborate effectively with remote repositories +- ✅ **Collaborate with teammates on shared repositories** +- ✅ **Resolve real merge conflicts in a team environment** +- ✅ **Create and review pull requests** +- ✅ **Use Git on a real cloud server (Gitea)** + +### From Advanced Track: +- ✅ Rebase to maintain clean, linear history +- ✅ Clean up messy commits before submitting pull requests - ✅ Work on multiple branches simultaneously with worktrees - ✅ Debug efficiently by finding bug-introducing commits with bisect +- ✅ Investigate code history with git blame +- ✅ Master different merge strategies and when to use each These are professional-level Git skills used daily by developers at top tech companies. ## For Workshop Facilitators -Before distributing this workshop to attendees: +This repository can be used for **self-paced learning** or as a **facilitated workshop**. + +### Self-Paced Distribution + +Before distributing this workshop to attendees for self-study: 1. **Delete the root `.git` directory**: This prevents confusion and ensures attendees practice git from scratch ```powershell @@ -232,3 +306,175 @@ Before distributing this workshop to attendees: ``` 2. Each module's `challenge/` directory will become its own independent git repository when attendees run `setup.ps1` 3. This isolation ensures each module provides a clean learning environment + +**Note**: Module 09 (Multiplayer) requires you to set up a Git server - see facilitator guide below. + +### Facilitated Workshop + +For running this as a full-day instructor-led workshop: + +1. **See [WORKSHOP-AGENDA.md](WORKSHOP-AGENDA.md)** - Complete agenda with timing, activities, and facilitation tips +2. **See [PRESENTATION-OUTLINE.md](PRESENTATION-OUTLINE.md)** - Slide deck outline for presentations +3. **Workshop covers:** Essentials 01-05 + Module 09 (Multiplayer collaboration exercise) +4. **Duration:** 6-7 hours including breaks +5. **Format:** Mix of presentation, live demos, and hands-on challenges + +**Facilitator preparation:** +- Review the workshop agenda thoroughly +- Set up Git server for Module 09 (see below) +- Ensure all participants have prerequisites installed (Git, PowerShell, Python) +- Prepare slides using the presentation outline +- Test all modules on a clean machine +- Create student accounts on your Git server + +The workshop format combines instructor-led sessions with self-paced hands-on modules for an engaging learning experience. + +### Setting Up Module 09: Multiplayer Git + +Module 09 requires a Git server for authentic collaboration. You have two options: + +**Option 1: Self-Hosted Gitea Server (Recommended)** + +Run your own Git server with Gitea using Docker and Cloudflare Tunnel: + +**Benefits:** +- 💰 Completely free (no cloud costs) +- 🔒 Full control over your data +- 🌐 Accessible from anywhere via Cloudflare Tunnel +- 🚀 Quick setup with Docker Compose +- 👥 Perfect for workshops with 2-24 students + +**Setup:** +1. See [GITEA-SETUP.md](GITEA-SETUP.md) for complete Gitea + Docker + Cloudflare Tunnel instructions +2. See `01_essentials/09-multiplayer/FACILITATOR-SETUP.md` for detailed workshop preparation: + - Creating student accounts + - Setting up The Great Print Project repository + - Pairing students + - Monitoring progress + - Troubleshooting common issues + +**Option 2: Azure DevOps / GitHub / GitLab** + +You can also use existing cloud Git platforms: +- Create organization/group for the workshop +- Set up repository with starter code (see facilitator guide) +- Create user accounts for students +- Configure permissions + +**Both options work - Gitea gives you more control and is free for any number of students.** + +--- + +## Repository Structure + +``` +git-workshop/ +├── README.md # This file +├── 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 (9 modules) +│ ├── 01-basics/ # Initialize, commit, status +│ ├── 02-history/ # Log, diff, show +│ ├── 03-branching/ # Create and switch branches +│ ├── 04-merging/ # Merge branches +│ ├── 05-merge-conflicts/ # Resolve conflicts step-by-step +│ ├── 06-cherry-pick/ # Apply specific commits +│ ├── 07-reset-vs-revert/ # Undo changes safely +│ ├── 08-stash/ # Save work-in-progress +│ └── 09-multiplayer/ # Real collaboration (cloud-based) +│ ├── README.md # Student guide (1,408 lines) +│ └── FACILITATOR-SETUP.md # Server setup guide (904 lines) +│ +└── 02_advanced/ # Professional techniques (6 modules) + ├── 01-rebasing/ # Linear history with rebase + ├── 02-interactive-rebase/ # Clean up commits + ├── 03-worktrees/ # Multiple branches simultaneously + ├── 04-bisect/ # Find bugs with binary search + ├── 05-blame/ # Code archaeology + └── 06-merge-strategies/ # Master merge techniques +``` + +## What's Unique About This Workshop + +### The Great Print Project (Module 09) + +Unlike any other Git tutorial, Module 09 provides **real collaborative experience**: + +- **Real Git server**: Not simulated - actual cloud repository at https://git.frod.dk/multiplayer +- **Real teammates**: Work in pairs on shared branches +- **Real conflicts**: Both partners edit the same code and must resolve conflicts together +- **Real pull requests**: Create PRs, review code, merge to main +- **Real success**: When all pairs merge, run `python main.py` and see everyone's contributions! + +**The challenge**: Each pair implements 3 Python functions (e.g., `print_b()`, `print_c()`, `print_d()`) in a shared repository. When complete, the program prints the alphabet A-Z and numbers 0-9. + +**What students learn**: +- Push/pull workflow with real teammates +- Handling rejected pushes (partner pushed first!) +- Resolving actual merge conflicts (not simulated) +- Creating meaningful pull requests +- Reviewing others' code +- Staying synchronized with a team + +This is how professional developers actually work - no simulation, no shortcuts. + +--- + +## Frequently Asked Questions + +**Q: Do I need to complete all modules?** +A: No! Essentials 01-05 covers what most developers use daily. Complete 06-09 and Advanced modules to deepen your skills. + +**Q: Can I do Module 09 (Multiplayer) without a partner?** +A: Not recommended - collaboration is the point. If solo, skip to Advanced modules or wait until you can pair with someone. + +**Q: How long does the workshop take?** +A: +- Essentials 01-05: 3-4 hours +- Full Essentials (01-09): 6-7 hours +- All modules: 12-15 hours +- Self-paced over several days works great! + +**Q: I'm stuck on a module. What should I do?** +A: +1. Re-read the module README.md +2. Check [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) +3. Run `./reset.ps1` to start fresh +4. Use `git status` and `git log --graph` to understand current state +5. For Module 09, ask your partner or facilitator + +**Q: Can I use this for a team workshop at my company?** +A: Absolutely! See the "For Workshop Facilitators" section above. The materials are designed for both self-study and instructor-led workshops. + +**Q: Do I need internet access?** +A: Modules 01-08 work completely offline. Module 09 requires internet to access the Git server. + +**Q: What if I prefer GitHub/GitLab instead of Gitea?** +A: The skills are identical across all Git platforms. Module 09 uses Gitea but everything you learn applies to GitHub, GitLab, Bitbucket, etc. + +--- + +## Contributing + +Found a bug or have a suggestion? Please open an issue or submit a pull request! + +--- + +## License + +This workshop is provided as-is for educational purposes. + +--- + +**Ready to master Git? Start with Essentials Module 01 and begin your journey!** + +```powershell +cd 01_essentials/01-basics +.\setup.ps1 +``` + +Happy Learning! 🚀