Initial commit

2025-11-29 18:20:25 +08:00
commit 0d6226e0d8
69 changed files with 20934 additions and 0 deletions
--- a/commands/commit-error-handling/handle-detached-head.md
+++ b/commands/commit-error-handling/handle-detached-head.md
@@ -0,0 +1,366 @@
+# Operation: Handle Detached HEAD State
+
+Handle detached HEAD state and provide solutions.
+
+## Purpose
+
+When git is in "detached HEAD" state, explain what this means and provide clear options for resolution.
+
+## Parameters
+
+None required - automatic detection and guidance.
+
+## Workflow
+
+### 1. Detect Detached HEAD State
+
+Check HEAD status:
+
+```bash
+# Check if HEAD is detached
+git symbolic-ref HEAD 2>/dev/null || echo "detached"
+
+# Get current commit
+git rev-parse --short HEAD
+
+# Check if any branch points here
+git branch --contains HEAD
+```
+
+### 2. Analyze Context
+
+Determine how user got into detached HEAD:
+
+```bash
+# Check reflog for recent operations
+git reflog -10
+
+# Check recent checkouts
+git reflog | grep "checkout:" | head -5
+
+# See what branches exist
+git branch -a
+```
+
+Common causes:
+- Checked out a specific commit SHA
+- Checked out a tag
+- During rebase or bisect operations
+- After certain git operations that move HEAD
+
+### 3. Explain Detached HEAD State
+
+#### Clear Explanation
+
+```
+DETACHED HEAD STATE
+━━━━━━━━━━━━━━━━━━━
+
+Current state:
+HEAD is at: abc1234
+Branch: (none - detached HEAD)
+
+What This Means:
+━━━━━━━━━━━━━━━━
+
+You are not on any branch. You're directly on commit abc1234.
+
+Why This Matters:
+━━━━━━━━━━━━━━━━
+
+- New commits you make won't be on any branch
+- When you switch branches, these commits become hard to find
+- You could lose work if you don't create a branch
+
+This is OK for:
+✅ Viewing old commits
+✅ Testing code at a specific point
+✅ Temporary exploration
+
+This is NOT OK for:
+❌ Making new commits you want to keep
+❌ Starting new work
+❌ Continuing development
+```
+
+### 4. Provide Resolution Options
+
+#### Option A: Create New Branch Here
+
+```
+SOLUTION A: Create a New Branch Here
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+If you want to keep working from this commit:
+
+1. Create and switch to new branch:
+   git checkout -b new-branch-name
+
+   OR (two steps):
+   git branch new-branch-name
+   git checkout new-branch-name
+
+2. Verify:
+   git status
+   # Should show "On branch new-branch-name"
+
+3. Continue working:
+   Make commits as normal
+   They'll be on the new branch
+
+Example:
+git checkout -b fix-issue-123
+```
+
+#### Option B: Return to a Branch
+
+```
+SOLUTION B: Return to Your Branch
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+If you were just exploring and want to go back:
+
+1. Switch to your branch:
+   git checkout main
+
+   OR:
+   git checkout <your-branch-name>
+
+2. Verify:
+   git status
+   # Should show "On branch main"
+
+Available branches:
+[List branches from git branch -a]
+
+Recent branch:
+git checkout -  # Goes to previous branch
+```
+
+#### Option C: Attach HEAD to Existing Branch
+
+```
+SOLUTION C: Attach HEAD to Existing Branch
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+If a branch already points to this commit:
+
+Current commit: abc1234
+Branches at this commit:
+[List from git branch --contains]
+
+1. Check out that branch:
+   git checkout <branch-name>
+
+2. Verify:
+   git branch
+   # Should show * next to branch name
+```
+
+#### Option D: Keep Commits Made in Detached HEAD
+
+If user already made commits in detached HEAD:
+
+```
+SOLUTION D: Preserve Commits Made in Detached HEAD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+You made commits while in detached HEAD.
+
+Current situation:
+- HEAD at: abc1234
+- Commits made: 3
+- These commits are not on any branch!
+
+To save them:
+
+1. Create branch from current position:
+   git checkout -b save-my-work
+
+2. Verify commits are there:
+   git log --oneline -5
+
+Your commits are now safe on "save-my-work" branch.
+
+Next steps:
+- Continue work on this branch, OR
+- Merge into another branch:
+  git checkout main
+  git merge save-my-work
+```
+
+### 5. Show Visual Diagram
+
+```
+VISUAL EXPLANATION
+━━━━━━━━━━━━━━━━━━
+
+Normal State (on a branch):
+━━━━━━━━━━━━━━━━━━━━━━━━━
+
+main → [commit 1] → [commit 2] → [commit 3]
+                                      ↑
+                                    HEAD
+
+HEAD points to branch "main"
+Branch "main" points to commit 3
+
+
+Detached HEAD State:
+━━━━━━━━━━━━━━━━━━━━
+
+main → [commit 1] → [commit 2] → [commit 3]
+
+              [commit X] ← HEAD (detached)
+
+HEAD points directly to commit X
+No branch points to commit X
+
+
+Making Commits in Detached HEAD:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+main → [commit 1] → [commit 2] → [commit 3]
+
+              [commit X] → [commit Y] ← HEAD (detached)
+
+If you checkout main now, commit Y becomes orphaned!
+
+
+Solution - Create Branch:
+━━━━━━━━━━━━━━━━━━━━━━━━
+
+main → [commit 1] → [commit 2] → [commit 3]
+
+new-branch → [commit X] → [commit Y] ← HEAD
+
+Now commits are safe on "new-branch"
+```
+
+### 6. Interactive Decision Support
+
+Guide user to choose:
+
+```
+What would you like to do?
+
+A) Create a new branch here and continue working
+   → Choose this if you want to keep this commit as a starting point
+
+B) Return to a branch (discard position)
+   → Choose this if you were just exploring
+
+C) Attach to an existing branch
+   → Choose this if a branch already points here
+
+D) Save commits I made while detached
+   → Choose this if you already made commits
+
+E) Not sure - need more explanation
+
+Please respond with A, B, C, D, or E.
+```
+
+## Error Handling
+
+### If not in detached HEAD
+
+```
+Not in detached HEAD state.
+
+Current state:
+Branch: main
+HEAD: abc1234
+
+You're on a normal branch. No action needed.
+```
+
+### If during special operation
+
+```
+Detached HEAD during rebase.
+
+This is temporary and expected.
+
+Actions:
+- Complete the rebase: git rebase --continue
+- OR abort: git rebase --abort
+
+After completing/aborting, HEAD will reattach automatically.
+```
+
+### If commits will be lost
+
+```
+⚠️  WARNING: Orphaned Commits Detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+You made 3 commits in detached HEAD:
+- abc1234 "commit message 1"
+- def5678 "commit message 2"
+- ghi9012 "commit message 3"
+
+If you switch branches now, these will be lost!
+
+REQUIRED ACTION: Create a branch first
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+git checkout -b save-my-commits
+
+Then you can safely work with these commits.
+```
+
+## Output Format
+
+Always provide:
+1. **Clear state description** - What detached HEAD means
+2. **Current situation** - What commit, how user got here
+3. **Multiple solutions** - All applicable options
+4. **Visual aids** - Diagrams if helpful
+5. **Specific commands** - Exact steps to resolve
+6. **Warnings** - If commits could be lost
+
+## Success Indicators
+
+After resolution:
+- HEAD is attached to a branch
+- `git branch` shows current branch with *
+- `git status` shows "On branch <name>"
+- User understands what happened
+- No commits were lost
+
+## Best Practices Guidance
+
+```
+AVOIDING DETACHED HEAD
+━━━━━━━━━━━━━━━━━━━━━━
+
+Prevention tips:
+
+1. Use branches for work:
+   git checkout -b feature-name
+   (not: git checkout abc1234)
+
+2. If checking out commits for inspection:
+   Remember you're in detached HEAD
+   Don't make commits you want to keep
+
+3. If you need to work on an old commit:
+   git checkout -b fix-branch abc1234
+   (Creates branch at that commit)
+
+4. Use tags for reference points:
+   git tag v1.0 abc1234
+   git checkout tags/v1.0
+   (Still detached, but purpose is clear)
+
+Remember:
+Detached HEAD is a valid state for temporary inspection,
+but always create a branch before making commits.
+```
+
+## Related Operations
+
+- After resolving, run **diagnose-issues** to verify state
+- Before creating branches, check with **history-analysis** for naming conventions
+- After attaching HEAD, continue with normal commit workflow