@icarusmx/creta 1.5.6 → 1.5.8

package/lib/exercises/iterm2-pane-navigation.md

@@ -0,0 +1,504 @@
+# iTerm2 Pane Navigation - Custom Keyboard Shortcuts
+
+<!-- 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: Default Pane Navigation is Awkward {{{
+
+You split your terminal with `Cmd + D`, but switching between panes requires:
+- **Default**: `Option + Cmd + Arrow`
+
+That's **three keys** just to move between panes. Way too much!
+
+**Common complaints:**
+- Too many modifier keys
+- Awkward hand position
+- Slows down your workflow
+
+}}}
+
+## ✅ Solution: Customize to Cmd + 0 (or any key you prefer) {{{
+
+You can change iTerm2's pane navigation shortcuts to something simpler.
+
+**Popular options:**
+- `Cmd + 0` (simple, one-handed)
+- `Cmd + Arrow` (directional)
+- `Cmd + [` and `]` (browser-style)
+- `Cmd + h/j/k/l` (vim-style)
+
+This guide shows you how to set **`Cmd + 0`** for cycling through panes.
+
+}}}
+
+## 🔧 Step-by-Step Configuration {{{
+
+### Step 1: Open iTerm2 Preferences {{{
+
+```bash
+# Keyboard shortcut
+Cmd + ,
+```
+
+**Or:** Click **iTerm2 menu** → **Preferences** (in the menu bar)
+
+}}}
+
+### Step 2: Navigate to Key Bindings {{{
+
+In the Preferences window:
+1. Click **"Keys"** tab at the top
+2. Click **"Key Bindings"** sub-tab (should already be selected)
+
+You'll see a list of all current keyboard shortcuts.
+
+}}}
+
+### Step 3: Remove Conflicting Binding {{{
+
+Before adding `Cmd + 0`, we need to remove the default binding:
+
+1. In the **search box** at the bottom, type: `⌘0`
+2. You'll see: **"Select Tab with Number 10"** or similar
+3. Click on it to select it
+4. Click the **`-`** (minus) button at the bottom left
+5. Confirm deletion
+
+**Why?** By default, `Cmd + 0-9` switches between tabs. Since most people don't use "go to tab 10", we can repurpose it.
+
+}}}
+
+### Step 4: Add New Pane Navigation Binding {{{
+
+Now let's add the new shortcut:
+
+1. Click the **`+`** (plus) button at the bottom left
+2. A dialog appears: **"Press shortcut"**
+3. Press **`Cmd + 0`** on your keyboard (it will show as `⌘0`)
+4. In the **"Action"** dropdown menu, select: **"Select Next Pane"**
+5. Click **"OK"**
+
+**Result:** Your new binding appears in the list!
+
+}}}
+
+### Step 5: Test It {{{
+
+Close the preferences window and test:
+
+```bash
+# Split terminal vertically
+Cmd + D
+
+# Split terminal horizontally
+Cmd + Shift + D
+
+# Now press Cmd + 0 to cycle through panes
+```
+
+Each press of `Cmd + 0` should move focus to the next pane in a circular pattern.
+
+}}}
+
+}}}
+
+## 🎯 Alternative Configurations {{{
+
+### Option 1: Directional Navigation (Cmd + Arrow) {{{
+
+If you prefer directional control instead of cycling:
+
+**Setup:**
+1. Remove conflicts: Search for `⌘←`, `⌘→`, `⌘↑`, `⌘↓` and delete them
+2. Add four bindings:
+   - `Cmd + Left Arrow` → **"Select Pane Left"**
+   - `Cmd + Right Arrow` → **"Select Pane Right"**
+   - `Cmd + Up Arrow` → **"Select Pane Above"**
+   - `Cmd + Down Arrow` → **"Select Pane Below"**
+
+**Pros:**
+- Intuitive directional control
+- No need to remember pane order
+
+**Cons:**
+- Four shortcuts to set up instead of one
+- May conflict with other apps
+
+}}}
+
+### Option 2: Browser-Style (Cmd + [ and ]) {{{
+
+**Setup:**
+1. Add two bindings:
+   - `Cmd + [` → **"Select Previous Pane"**
+   - `Cmd + ]` → **"Select Next Pane"**
+
+**Pros:**
+- Similar to browser tab navigation
+- Only two keys to remember
+
+**Cons:**
+- Not directional (cycles through panes)
+
+}}}
+
+### Option 3: Vim-Style (Cmd + h/j/k/l) {{{
+
+**Setup:**
+1. Add four bindings:
+   - `Cmd + h` → **"Select Pane Left"**
+   - `Cmd + j` → **"Select Pane Below"**
+   - `Cmd + k` → **"Select Pane Above"**
+   - `Cmd + l` → **"Select Pane Right"**
+
+**Pros:**
+- Natural for vim users
+- Home row keys (fast)
+
+**Cons:**
+- Conflicts with shell shortcuts (Ctrl+L clears screen in some setups)
+
+}}}
+
+### Option 4: Two-Key Cycling (Cmd + 0 and Cmd + 9) {{{
+
+**Setup:**
+1. Remove conflicts for both `⌘0` and `⌘9`
+2. Add bindings:
+   - `Cmd + 0` → **"Select Next Pane"**
+   - `Cmd + 9` → **"Select Previous Pane"**
+
+**Pros:**
+- Cycle forward and backward
+- Only two shortcuts
+
+**Cons:**
+- Still cycles, not directional
+
+}}}
+
+}}}
+
+## 🔍 Finding the Right Action {{{
+
+When adding a key binding, iTerm2 offers many actions. Here are the pane-related ones:
+
+### Pane Selection Actions {{{
+
+**Cycling (circular navigation):**
+- `Select Next Pane` - Move to next pane clockwise
+- `Select Previous Pane` - Move to previous pane counter-clockwise
+
+**Directional (precise navigation):**
+- `Select Pane Left` - Move focus to pane on the left
+- `Select Pane Right` - Move focus to pane on the right
+- `Select Pane Above` - Move focus to pane above
+- `Select Pane Below` - Move focus to pane below
+
+**Other useful actions:**
+- `Split Horizontally` - Create new horizontal split
+- `Split Vertically` - Create new vertical split (already `Cmd+D`)
+- `Move to Split Pane...` - Interactive pane selector
+
+}}}
+
+### How to Search for Actions {{{
+
+In the "Action" dropdown:
+1. Start typing to filter (e.g., "pane", "split", "select")
+2. Scroll to find the exact action you need
+3. Preview the action description
+
+}}}
+
+}}}
+
+## 🛡️ Conflict Resolution {{{
+
+### Common Conflicts {{{
+
+**System Shortcuts:**
+- `Cmd + Arrow` - Mission Control, Switch Spaces (macOS)
+- `Cmd + [` - Back (browsers, many apps)
+- `Cmd + ]` - Forward (browsers, many apps)
+
+**App Shortcuts:**
+- `Cmd + 0` - Reset zoom (some apps)
+- `Cmd + h/j/k/l` - Various vim-style apps
+
+**Solution:** Choose shortcuts that don't conflict with your most-used apps.
+
+}}}
+
+### Checking for Conflicts {{{
+
+Before assigning a shortcut:
+
+1. **Try it in iTerm2** - Does it do something already?
+2. **Try it in your browser** - Common conflict area
+3. **Try it in your editor** - VSCode, Neovim, etc.
+
+If there's a conflict, pick a different key combination.
+
+}}}
+
+### Safe Shortcut Choices {{{
+
+**Least likely to conflict:**
+- `Cmd + 0` (if you don't use tab 10)
+- `Cmd + 9` (if you don't use tab 9)
+- `Ctrl + Cmd + Arrow` (more modifier keys, but safe)
+- `Option + Arrow` (simpler than default)
+
+**Test before committing!**
+
+}}}
+
+}}}
+
+## 🧪 Practice Exercise {{{
+
+Try this to get comfortable with your new shortcuts:
+
+### Exercise 1: Basic Pane Navigation {{{
+
+```bash
+# 1. Split into 4 panes
+Cmd + D          # Vertical split (2 panes)
+Cmd + Shift + D  # Horizontal split (3 panes)
+Cmd + 0          # Move to another pane
+Cmd + D          # Split again (4 panes)
+
+# 2. Practice navigating
+Cmd + 0  # Cycle through each pane
+Cmd + 0  # Keep pressing to make a full circle
+Cmd + 0
+Cmd + 0  # Back to first pane
+
+# 3. Run commands in each pane
+# Pane 1: ls
+# Pane 2: git status
+# Pane 3: npm run dev
+# Pane 4: tail -f logs/app.log
+
+# 4. Navigate while commands run
+Cmd + 0  # Jump between running processes
+```
+
+}}}
+
+### Exercise 2: Real Workflow Simulation {{{
+
+Simulate a full-stack development workflow:
+
+```bash
+# Pane 1 (top-left): Backend server
+cd ~/projects/my-app/backend
+npm run dev
+
+# Pane 2 (top-right): Frontend server
+Cmd + D  # Split vertically
+cd ~/projects/my-app/frontend
+npm run dev
+
+# Pane 3 (bottom-left): Git operations
+Cmd + Shift + D  # Split horizontally
+git status
+
+# Pane 4 (bottom-right): Database
+Cmd + 0  # Navigate to pane 2
+Cmd + Shift + D  # Split it horizontally
+mongod
+
+# Navigate freely
+Cmd + 0  # Cycle through to monitor all processes
+```
+
+**Practice navigating while processes are running** - this is the real use case!
+
+}}}
+
+}}}
+
+## 📚 Quick Reference {{{
+
+### Default iTerm2 Pane Shortcuts {{{
+
+```bash
+# Splitting
+Cmd + D                 # Split vertically
+Cmd + Shift + D         # Split horizontally
+
+# Navigation (DEFAULT)
+Option + Cmd + Arrow    # Navigate between panes
+Cmd + [                 # Previous pane (default)
+Cmd + ]                 # Next pane (default)
+
+# Closing
+Cmd + W                 # Close current pane
+Cmd + Option + W        # Close all panes except current
+```
+
+}}}
+
+### Your Custom Setup (Cmd + 0) {{{
+
+```bash
+# After configuration:
+Cmd + D          # Split vertically (unchanged)
+Cmd + Shift + D  # Split horizontally (unchanged)
+Cmd + 0          # Cycle to next pane (NEW!)
+Cmd + 9          # Cycle to previous pane (OPTIONAL)
+```
+
+}}}
+
+### Configuration Summary {{{
+
+**To set up Cmd + 0 navigation:**
+
+1. Open: `Cmd + ,` → Keys → Key Bindings
+2. Remove: `⌘0` binding (Select Tab 10)
+3. Add: `⌘0` → "Select Next Pane"
+4. Test: Split panes and press `Cmd + 0`
+
+**Done!** 🎉
+
+}}}
+
+}}}
+
+## 🎓 Advanced Tips {{{
+
+### Save Custom Key Bindings as Preset {{{
+
+Once you've customized your shortcuts:
+
+1. Preferences → Keys → Key Bindings
+2. Click **"Presets"** dropdown (bottom)
+3. Select **"Duplicate Current Preset"**
+4. Name it: "My Custom Navigation"
+5. Export it: Presets → Export → Save `.json` file
+
+**Why?**
+- Backup your configuration
+- Share across machines
+- Restore if iTerm2 resets
+
+}}}
+
+### Profile-Specific Shortcuts {{{
+
+You can have different shortcuts for different profiles:
+
+1. Preferences → Profiles → [Your Profile]
+2. Go to **Keys** tab
+3. Check **"A hotkey opens a dedicated window with this profile"**
+4. Configure profile-specific key bindings
+
+**Use case:** Different shortcuts for different projects!
+
+}}}
+
+### Combine with Tmux {{{
+
+If you use tmux inside iTerm2:
+
+**iTerm2 shortcuts** control iTerm2 panes
+**Tmux shortcuts** (e.g., `Ctrl+B + Arrow`) control tmux panes
+
+**Best practice:**
+- Use iTerm2 panes for different servers/services
+- Use tmux panes for same-context workflows
+- Keep shortcuts distinct to avoid conflicts
+
+}}}
+
+}}}
+
+## 🐛 Troubleshooting {{{
+
+### Shortcut Not Working {{{
+
+**Check 1: Conflict**
+- Another app might be capturing the shortcut
+- Test in different apps to confirm
+
+**Check 2: Profile Override**
+- Some profiles override global key bindings
+- Check Preferences → Profiles → [Profile] → Keys
+
+**Check 3: macOS System Preferences**
+- System Preferences → Keyboard → Shortcuts
+- Look for conflicting system shortcuts
+
+**Fix:** Choose a different key combination or disable the conflicting shortcut.
+
+}}}
+
+### Changes Not Saving {{{
+
+**Possible causes:**
+- iTerm2 preferences file is read-only
+- Profile is overriding global settings
+- Need to restart iTerm2
+
+**Fix:**
+```bash
+# 1. Close all iTerm2 windows
+Cmd + Q  # Fully quit iTerm2
+
+# 2. Reopen iTerm2
+# 3. Check if changes persist
+```
+
+}}}
+
+### Accidentally Deleted Important Shortcut {{{
+
+**Fix: Restore defaults**
+1. Preferences → Keys → Key Bindings
+2. Click **"Presets"** dropdown
+3. Select **"Factory Defaults"**
+4. Confirm restoration
+
+**Warning:** This removes ALL custom shortcuts!
+
+**Better approach:** Export your config before experimenting (see Advanced Tips).
+
+}}}
+
+}}}
+
+## 💡 Recommended Setup for Most Users {{{
+
+After trying many configurations, here's what works best for most developers:
+
+```bash
+Cmd + D          # Split vertically (default)
+Cmd + Shift + D  # Split horizontally (default)
+Cmd + 0          # Next pane (custom)
+Cmd + 9          # Previous pane (custom)
+Cmd + W          # Close pane (default)
+```
+
+**Why this works:**
+- Simple to remember (just 0 and 9)
+- One-handed operation
+- Doesn't conflict with most apps
+- Fast enough for daily use
+
+**Advanced users** might prefer directional arrows, but for most workflows, cycling with 0/9 is sufficient and simpler.
+
+}}}
+
+---
+
+**Remember:** The best keyboard shortcuts are the ones you'll actually use. Start simple, then customize as needed! ⌨️