feat: add initial module 04

module-04-merging/README.md

@@ -0,0 +1,97 @@
+# Module 04: Merging
+
+## Learning Objectives
+
+In this module, you will:
+- Understand what merging means in Git
+- Perform a fast-forward merge
+- Perform a three-way merge
+- Understand when merge commits are created
+- Use `git merge` to combine branches
+
+## Challenge
+
+### Setup
+
+Run the setup script to create your challenge environment:
+
+```powershell
+.\setup.ps1
+```
+
+This will create a `challenge/` directory with a Git repository that has a main branch and a feature branch ready to merge.
+
+### Your Task
+
+This challenge has two parts that teach you about the two types of merges in Git:
+
+**Part 1: Fast-Forward Merge**
+1. Merge the existing `feature-api` branch into main
+2. Observe that this is a "fast-forward" merge (no merge commit created)
+
+**Part 2: Three-Way Merge**
+3. Create a new branch called `feature-ui`
+4. Make commits on the feature-ui branch
+5. Switch back to main and make a commit there too (creates divergence)
+6. Merge feature-ui into main
+7. Observe that this creates a merge commit (three-way merge)
+
+**Suggested Approach:**
+
+1. Navigate to the challenge directory: `cd challenge`
+2. Check current branch: `git branch` (should be on main)
+3. View existing branches: `git branch -a`
+4. Merge feature-api: `git merge feature-api`
+5. View the log: `git log --oneline --graph`
+6. Create feature-ui branch: `git checkout -b feature-ui`
+7. Create a new file `ui.py` and commit it
+8. Make another commit on feature-ui (modify ui.py)
+9. Switch back to main: `git checkout main`
+10. Make a change on main (modify api.py) and commit it
+11. Merge feature-ui: `git merge feature-ui`
+12. View the merge history: `git log --oneline --graph --all`
+
+> **Important Notes:**
+> - A **fast-forward merge** happens when main hasn't changed since the feature branch was created
+> - A **three-way merge** creates a merge commit when both branches have diverged
+> - You can see merge commits with `git log --merges`
+> - The `--graph` option helps visualize the branch history
+> - After merging, the feature branch still exists but you can delete it with `git branch -d`
+
+## Key Concepts
+
+- **Merge**: Combining changes from different branches into one branch.
+- **Fast-Forward Merge**: When the target branch hasn't changed, Git simply moves the branch pointer forward. No merge commit is created.
+- **Three-Way Merge**: When both branches have new commits, Git creates a merge commit that has two parent commits.
+- **Merge Commit**: A special commit with two (or more) parent commits, representing the point where branches were merged.
+- **Divergent Branches**: Branches that have different commits since they split from a common ancestor.
+
+## Useful Commands
+
+```bash
+git merge <branch>           # Merge branch into current branch
+git log --oneline --graph    # View merge history visually
+git log --graph --all        # View all branches and merges
+git log --merges             # Show only merge commits
+git branch -d <branch>       # Delete a merged branch (optional)
+```
+
+## Verification
+
+Once you've completed both merges, verify your solution:
+
+```powershell
+.\verify.ps1
+```
+
+The verification script will check that you've successfully merged both feature branches and understand the different merge types.
+
+## Need to Start Over?
+
+If you want to reset the challenge and start fresh:
+
+```powershell
+.\reset.ps1
+```
+
+This will remove the challenge directory and run the setup script again, giving you a clean slate.