@icarusmx/creta 1.5.4 → 1.5.6

package/lib/exercises/git-stash-workflow.md

@@ -0,0 +1,426 @@
+# Git Stash Workflow - Wrong Branch Recovery
+
+<!-- vim: set foldmethod=marker foldlevel=0: -->
+
+## 📖 LazyVim Reading Guide {{{
+
+**Start with:** `zM` (close all folds) → Navigate with `za` (toggle fold under cursor)
+
+This document uses fold markers `{{{` and `}}}` for organized reading.
+
+}}}
+
+## 🚨 Problem: Made Changes on Main Instead of Dev {{{
+
+You're coding away, making changes, and suddenly realize: **"Oh no, I'm on `main` not `dev`!"**
+
+This is a common mistake. Here's the **clean recovery workflow** using `git stash`.
+
+}}}
+
+## ✅ Solution: Stash → Switch → Pop {{{
+
+### Step 1: Stash Your Changes {{{
+
+```bash
+# Stash ALL changes (tracked + untracked files)
+git stash push -u -m "WIP: changes meant for dev branch"
+```
+
+**Flags explained:**
+- `-u` or `--include-untracked`: Stash untracked files too (new files you created)
+- `-m "message"`: Give your stash a descriptive name so you remember what it is
+
+**What happens:**
+- Your working directory becomes clean
+- All changes are safely stored in the stash
+- You're still on `main` branch
+
+}}}
+
+### Step 2: Switch to Correct Branch {{{
+
+```bash
+# Switch to dev branch
+git checkout dev
+```
+
+**Now you're on the correct branch** with a clean working directory.
+
+}}}
+
+### Step 3: Apply Stashed Changes {{{
+
+```bash
+# Apply and remove the stash
+git stash pop
+```
+
+**What happens:**
+- Your stashed changes are applied to `dev` branch
+- The stash is removed from the stash list
+- You can now continue working
+
+**Alternative:** Use `git stash apply` if you want to keep the stash (doesn't remove it)
+
+}}}
+
+}}}
+
+## 🔍 Checking Your Stash {{{
+
+### List All Stashes {{{
+
+```bash
+git stash list
+```
+
+**Output example:**
+```
+stash@{0}: On main: WIP: changes meant for dev branch
+stash@{1}: On main: experimental feature attempt
+```
+
+}}}
+
+### View Stash Contents {{{
+
+```bash
+# Show what's in the most recent stash
+git stash show
+
+# Show full diff
+git stash show -p
+
+# Show specific stash
+git stash show stash@{1}
+```
+
+}}}
+
+### Apply Specific Stash {{{
+
+```bash
+# Apply a specific stash (keeps it in the list)
+git stash apply stash@{1}
+
+# Pop a specific stash (removes it from the list)
+git stash pop stash@{1}
+```
+
+}}}
+
+### Delete Stash {{{
+
+```bash
+# Drop specific stash
+git stash drop stash@{0}
+
+# Clear all stashes (careful!)
+git stash clear
+```
+
+}}}
+
+}}}
+
+## 🎯 Real-World Scenarios {{{
+
+### Scenario 1: Uncommitted Changes on Wrong Branch {{{
+
+**Problem:**
+```bash
+$ git status
+On branch main
+Changes not staged for commit:
+  modified:   bin/creta.js
+  modified:   package.json
+
+Untracked files:
+  lib/exercises/
+```
+
+**Solution:**
+```bash
+# 1. Stash everything
+git stash push -u -m "WIP: lesson 7 improvements"
+
+# 2. Switch to dev
+git checkout dev
+
+# 3. Apply changes
+git stash pop
+
+# 4. Continue working
+git status  # Now on dev with your changes
+```
+
+}}}
+
+### Scenario 2: Already Made Commits on Main {{{
+
+**Problem:** You committed changes to `main` that should be on `dev`.
+
+**Solution: Cherry-pick approach**
+```bash
+# 1. Note the commit hash
+git log --oneline -1
+# ddbd498 add refactor.txt file
+
+# 2. Switch to dev
+git checkout dev
+
+# 3. Cherry-pick the commit
+git cherry-pick ddbd498
+
+# 4. Go back to main and reset
+git checkout main
+git reset --hard HEAD~1  # Remove the last commit from main
+```
+
+**Caution:** Only do this if you **haven't pushed** to remote yet!
+
+}}}
+
+### Scenario 3: Mixed - Some Committed, Some Uncommitted {{{
+
+**Solution: Combine both approaches**
+```bash
+# 1. Stash uncommitted changes
+git stash push -u -m "WIP: uncommitted work"
+
+# 2. Note committed hash
+git log --oneline -1
+
+# 3. Switch to dev
+git checkout dev
+
+# 4. Cherry-pick the commit
+git cherry-pick <hash>
+
+# 5. Pop the stash
+git stash pop
+
+# 6. Clean up main
+git checkout main
+git reset --hard HEAD~1
+```
+
+}}}
+
+}}}
+
+## 🛡️ Best Practices {{{
+
+### Prevention {{{
+
+1. **Check branch before coding:**
+   ```bash
+   git branch  # Shows current branch with *
+   ```
+
+2. **Use git prompt in shell** (shows current branch in prompt)
+   - Oh-My-Zsh, Starship, etc.
+
+3. **Create feature branches immediately:**
+   ```bash
+   git checkout -b feature/lesson-7-fix
+   ```
+
+}}}
+
+### Working with Stash {{{
+
+1. **Always use descriptive messages** with `-m`
+   - ❌ `git stash`
+   - ✅ `git stash push -u -m "WIP: implementing user auth"`
+
+2. **Stash frequently** when switching contexts
+   ```bash
+   git stash push -m "WIP: pausing to fix urgent bug"
+   git checkout hotfix-branch
+   # ... fix bug ...
+   git checkout -
+   git stash pop
+   ```
+
+3. **Don't let stashes pile up** - apply or drop them regularly
+
+}}}
+
+### Safety {{{
+
+1. **Never `git stash clear`** unless you're 100% sure
+2. **Before `git reset --hard`** - make sure you haven't pushed
+3. **Check stash contents** before popping: `git stash show -p`
+
+}}}
+
+}}}
+
+## 🧪 Practice Exercise {{{
+
+Try this safe simulation:
+
+```bash
+# 1. Create a test scenario
+echo "test" > test-file.txt
+git status  # See untracked file
+
+# 2. Stash it
+git stash push -u -m "test stash practice"
+
+# 3. Verify it's gone
+ls test-file.txt  # Should error (file doesn't exist)
+
+# 4. Check stash
+git stash list
+git stash show -p
+
+# 5. Restore it
+git stash pop
+
+# 6. Clean up
+rm test-file.txt
+```
+
+}}}
+
+## 📚 Quick Reference {{{
+
+```bash
+# Stash with untracked files
+git stash push -u -m "descriptive message"
+
+# List stashes
+git stash list
+
+# Show stash contents
+git stash show -p
+
+# Apply and keep stash
+git stash apply
+
+# Apply and remove stash
+git stash pop
+
+# Apply specific stash
+git stash pop stash@{1}
+
+# Delete specific stash
+git stash drop stash@{0}
+
+# Delete all stashes (CAREFUL!)
+git stash clear
+```
+
+}}}
+
+## 🔬 Diagnostic Commands - Understanding Your Situation {{{
+
+Before fixing anything, you need to understand what you're dealing with. These commands help you see the full picture.
+
+### Visualize Branch Divergence {{{
+
+```bash
+git log --oneline --all --graph --decorate -10
+```
+
+**What each flag does:**
+- `--oneline`: Show each commit as one line (compact view)
+- `--all`: Show ALL branches (not just current branch)
+- `--graph`: Draw a text-based graph showing branch structure
+- `--decorate`: Show branch names and tags next to commits
+- `-10`: Limit to last 10 commits
+
+**Output example:**
+```
+* 4093951 (dev) add new strategic route for creta cli
+* 1348508 add os fundamentals
+* fb1fca8 try to make one big lesson
+| * ddbd498 (HEAD -> main) add refactor.txt file
+| * 31a47a2 first commands
+|/
+* b01a857 initial commit
+```
+
+**What this tells you:**
+- `dev` and `main` have diverged from commit `b01a857`
+- `dev` has 3 new commits
+- `main` has 2 new commits
+- They're on different paths! 🚨
+
+}}}
+
+### Compare Branches {{{
+
+```bash
+# Show commits on main that aren't on dev
+git log dev..main --oneline
+
+# Show commits on dev that aren't on main
+git log main..dev --oneline
+
+# Show all differences between branches
+git log --left-right --oneline main...dev
+```
+
+**Interpret results:**
+- Empty output = branches are in sync
+- Commits listed = those commits are unique to one branch
+
+}}}
+
+### Check Current Status {{{
+
+```bash
+# What branch am I on?
+git branch
+
+# What's changed?
+git status
+
+# What commits are recent?
+git log --oneline -5
+
+# Did I already push this?
+git log @{u}..HEAD  # Shows unpushed commits
+```
+
+}}}
+
+### Understanding Main vs Dev State {{{
+
+```bash
+# Is main ahead of dev?
+git rev-list --left-right --count main...dev
+
+# Output: "2	3" means:
+# - main has 2 commits dev doesn't have
+# - dev has 3 commits main doesn't have
+```
+
+**Decision tree:**
+- `0	X`: Main is behind → merge dev into main
+- `X	0`: Main is ahead → merge main into dev
+- `X	Y`: Branches diverged → need to decide merge strategy
+
+}}}
+
+}}}
+
+## 🎓 Related Git Workflows {{{
+
+- **Branch switching:** `git checkout <branch>`
+- **Create branch:** `git checkout -b <new-branch>`
+- **Cherry-pick:** `git cherry-pick <commit-hash>`
+- **Reset commits:** `git reset --hard HEAD~1`
+- **View history:** `git log --oneline --graph`
+- **Visualize all branches:** `git log --oneline --all --graph --decorate`
+- **Compare branches:** `git log branch1..branch2`
+
+}}}
+
+---
+
+**Remember:** Stash is your safety net. When in doubt, stash it out! 🎯