feat: split out git blame

03_advanced/05-blame/README.md

@@ -0,0 +1,169 @@
+# Module 05: Git Blame - Code Archaeology
+
+## Learning Objectives
+
+In this module, you will:
+- Use `git blame` to find who made specific changes
+- Understand blame output format and information
+- Track down problematic code changes
+- Learn when and why to use `git blame`
+- Investigate code history to understand context
+
+## 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 security issue - someone committed hardcoded credentials!
+
+### Your Task
+
+Your team has discovered a security vulnerability: hardcoded credentials were added to the codebase. Your job is to investigate who made this change and document your findings.
+
+The setup script will create an `investigation.md` file in the challenge directory with questions for you to answer. Use `git blame` and other Git commands to track down the responsible developer.
+
+**Scenario:**
+- Someone added hardcoded login credentials (`username: "admin"`, `password: "admin123"`) to `app.py`
+- This is a critical security issue
+- You need to identify who made this change so the team can discuss it with them
+
+**Suggested Approach:**
+
+1. Navigate to the challenge directory: `cd challenge`
+2. Open `investigation.md` to see the questions
+3. Examine `app.py` to find the suspicious line
+4. Use `git blame` to find who wrote that line
+5. Use `git blame -e` to see email addresses
+6. Use `git show` to see the full commit details
+7. Document your findings in `investigation.md`
+
+> **Important Notes:**
+> - `git blame` shows who last modified each line
+> - Each line shows: commit hash, author, date, line number, and content
+> - Use `-e` flag to show email addresses
+> - Use `-L` to focus on specific line ranges
+
+## Key Concepts
+
+- **Git Blame**: Shows the revision and author who last modified each line of a file
+- **Code Archaeology**: Using Git history to understand when and why code changed
+- **Author Attribution**: Identifying who wrote specific code for context, not punishment
+- **Commit Context**: Understanding the full story behind a change
+
+## Understanding Git Blame Output
+
+When you run `git blame app.py`, you'll see output like this:
+
+```
+a1b2c3d4 (John Doe     2024-01-15 10:30:45 +0000  1) # app.py - Main application
+a1b2c3d4 (John Doe     2024-01-15 10:30:45 +0000  2)
+e5f6g7h8 (Jane Smith   2024-01-16 14:20:10 +0000  3) from auth import login
+e5f6g7h8 (Jane Smith   2024-01-16 14:20:10 +0000  4)
+i9j0k1l2 (Bob Wilson   2024-01-17 09:15:30 +0000  5) def main():
+i9j0k1l2 (Bob Wilson   2024-01-17 09:15:30 +0000  6)     login("admin", "admin123")
+```
+
+### Breaking It Down
+
+Each line shows:
+1. **Commit Hash** (`a1b2c3d4`) - The commit that last changed this line
+2. **Author Name** (`John Doe`) - Who made the change
+3. **Date/Time** (`2024-01-15 10:30:45 +0000`) - When it was changed
+4. **Line Number** (`1`) - The line number in the current file
+5. **Line Content** (`# app.py - Main application`) - The actual code
+
+### Useful Git Blame Options
+
+```bash
+git blame <file>                 # Basic blame output
+git blame -e <file>              # Show email addresses instead of names
+git blame -L 10,20 <file>        # Only show lines 10-20
+git blame -L 10,+5 <file>        # Show 5 lines starting from line 10
+git blame -w <file>              # Ignore whitespace changes
+git blame <commit> <file>        # Blame as of specific commit
+```
+
+### Following Up After Blame
+
+Once you find the commit hash:
+
+```bash
+git show <commit-hash>           # See the full commit details
+git log -p <commit-hash>         # See commit with diff
+git show <commit-hash> --stat    # See which files were changed
+```
+
+## When to Use Git Blame
+
+**Good reasons to use `git blame`:**
+- 🔍 Understanding why code was written a certain way
+- 📚 Finding context for a piece of code
+- 🐛 Identifying when a bug was introduced
+- 💡 Discovering the thought process behind a decision
+- 👥 Finding who to ask about specific code
+
+**Not for blaming:**
+- ❌ Finding someone to blame for mistakes
+- ❌ Tracking "productivity" or code ownership
+- ❌ Punishing developers for old code
+
+**Remember:** Code archaeology is about understanding, not blaming!
+
+## Useful Commands
+
+### Investigation Commands
+
+```bash
+# Find who changed each line
+git blame <file>
+git blame -e <file>              # With email addresses
+
+# Focus on specific lines
+git blame -L 10,20 <file>        # Lines 10-20
+git blame -L :function_name <file>  # Specific function (Git 2.20+)
+
+# See historical blame
+git blame <commit>^ <file>       # Blame before a specific commit
+
+# Combine with grep
+git blame <file> | grep "pattern"  # Find who wrote lines matching pattern
+```
+
+### Context Commands
+
+```bash
+# See full commit details
+git show <commit-hash>
+git log -1 <commit-hash>         # Just the commit message
+
+# See all commits by author
+git log --author="name"
+
+# See what else changed in that commit
+git show <commit-hash> --stat
+```
+
+## Verification
+
+Once you've completed your investigation in `investigation.md`, verify your solution:
+
+```powershell
+.\verify.ps1
+```
+
+The verification script will check that you've identified the correct developer.
+
+## 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.