floppydiscen/git-workshop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: update README after big changes

Browse Source
This commit is contained in:
Bjarke Sporring
2026-01-07 23:51:49 +01:00
parent 7f34cf2d08
commit 0a9f7c1842
1 changed files with 291 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

336
README.md
View File

@@ -1,35 +1,43 @@
# Git Workshop # 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 ## Workshop Structure
Each module is a self-contained challenge that teaches specific git concepts: The workshop is organized into two tracks:
### Beginner Level ### 01 Essentials - Core Git Skills (9 modules)
- **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
### Intermediate Level Master fundamental Git concepts and collaborative workflows:
- **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
### Advanced Level - **Module 01: Git Basics** - Initialize repositories, stage changes, make commits
- **Module 09**: Reset vs Revert - Understand when to rewrite history vs create new commits - **Module 02: Viewing History** - Use git log and git diff to explore project history
- **Module 10**: Stash - Temporarily save work without committing - **Module 03: Branching Basics** - Create, switch, and manage branches
- **Module 11**: Working with Remotes - Clone, push, pull, and fetch from remote repositories - **Module 04: Merging** - Combine branches and understand merge workflows
- **Module 12**: Worktrees - Work on multiple branches simultaneously - **Module 05: Merge Conflicts** - Identify, understand, and resolve merge conflicts step-by-step
- **Module 13**: Bisect - Use binary search to find bugs in commit history - **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 ## 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 2. Read the `README.md` to understand the challenge
3. Run `./setup.ps1` to create the challenge environment 3. Run `./setup.ps1` to create the challenge environment
4. Complete the challenge using git commands 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! **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 ## 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 ### Windows
@@ -59,7 +80,8 @@ Then run scripts using:
First, make sure scripts are executable (only needed once): First, make sure scripts are executable (only needed once):
```bash ```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: 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 $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 ### Basic Command Line Knowledge
You should know how to: 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 - **HEAD**: A pointer showing which commit you're currently working from
- **main/master**: The primary branch in a repository (main is the modern convention) - **main/master**: The primary branch in a repository (main is the modern convention)
- **Merge**: Combining changes from different branches - **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! Don't worry if these don't make sense yet - you'll learn them hands-on as you progress!
## Getting Started ## Getting Started
Start with Module 01: Start with Essentials Module 01:
```powershell ```powershell
cd module-01-basics cd 01_essentials/01-basics
.\setup.ps1 .\setup.ps1
``` ```
@@ -177,54 +207,98 @@ Follow the instructions in each module's README.md file.
## What Makes This Workshop Different ## What Makes This Workshop Different
- **Hands-On Practice**: Each module creates a real Git scenario you must solve - **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 - **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 - **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 ## Learning Path
The modules are designed to build on each other: The modules are designed to build on each other:
1. **Start Here** (Modules 1-3): Core Git fundamentals everyone needs ### Recommended Progression
2. **Collaboration** (Modules 4-5): Working with branches and resolving conflicts
3. **History Management** (Modules 6-8): Rewriting and organizing commits **Phase 1: Core Fundamentals (Essentials 01-03)**
4. **Advanced Workflows** (Modules 9-11): Professional Git techniques - Git Basics, History, Branching
5. **Power User** (Modules 12-13): Advanced tools for productivity and debugging - **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 ## Tips for Success
- Don't skip modules - each builds on previous concepts - **Don't skip modules** - each builds on previous concepts
- Read the README.md thoroughly before starting each challenge - **Read the README.md thoroughly** before starting each challenge
- Keep [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) open as a quick reference - **Keep [GIT-CHEATSHEET.md](GIT-CHEATSHEET.md) open** as a quick reference
- Experiment freely - you can always run `./reset.ps1` to start over - **Experiment freely** - you can always run `./reset.ps1` to start over
- Use `git log --oneline --graph --all` frequently to visualize repository state - **Use `git log --oneline --graph --all`** frequently to visualize repository state
- If stuck, check the Key Concepts section in the module's README - **If stuck**, check the Key Concepts section in the module's README
- Consider installing glow for better markdown reading experience - **Consider installing glow** for better markdown reading experience
- **For Module 09**, work with a partner - collaboration is the point!
## Skills You'll Master ## Skills You'll Master
By completing this workshop, you'll be able to: By completing this workshop, you'll be able to:
### From Essentials Track:
- ✅ Create and manage Git repositories with confidence - ✅ Create and manage Git repositories with confidence
- ✅ Navigate project history and understand what changed when - ✅ Navigate project history and understand what changed when
- ✅ Use branches effectively for parallel development - ✅ Use branches effectively for parallel development
- ✅ Merge branches and resolve conflicts like a pro - ✅ Merge branches and resolve conflicts like a pro
- ✅ Rebase to maintain clean, linear history - ✅ Apply specific commits with cherry-pick
- ✅ Clean up messy commits before submitting pull requests
- ✅ Cherry-pick specific commits across branches
- ✅ Choose correctly between reset and revert - ✅ Choose correctly between reset and revert
- ✅ Use stash to manage work-in-progress without commits - ✅ 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 - ✅ Work on multiple branches simultaneously with worktrees
- ✅ Debug efficiently by finding bug-introducing commits with bisect - ✅ 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. These are professional-level Git skills used daily by developers at top tech companies.
## For Workshop Facilitators ## 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 1. **Delete the root `.git` directory**: This prevents confusion and ensures attendees practice git from scratch
```powershell ```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` 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 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! 🚀