@bobfrankston/npmglobalize 1.0.35 → 1.0.36

package/README.md

@@ -184,6 +184,37 @@ git config core.eol lf          # Force LF line endings
 
 This ensures consistent line endings across Windows, macOS, and Linux, preventing "modified file" issues caused by line ending differences.
 
+### 🔍 Understanding "Detached HEAD" Error
+
+**What is Detached HEAD?**
+Your git repository is not currently on a branch (like `master` or `main`). This happens when you:
+- Check out a specific commit: `git checkout abc123`
+- Check out a tag: `git checkout v1.0.0`
+- Have some git operations leave you in this state
+
+**Why does it matter?**
+Publishing requires being on a branch so commits and tags can be properly tracked in your repository history.
+
+**Common scenarios:**
+
+1. **Just fixing files with `--conform`:**
+   ```bash
+   npmglobalize --conform   # ✓ Files get fixed, then exits with helpful message
+   ```
+   The files are already updated! You don't need to run it again.
+
+2. **Want to publish:**
+   ```bash
+   git checkout master      # Get back on a branch
+   npmglobalize            # Now works normally
+   ```
+
+3. **Force publish anyway (not recommended):**
+   ```bash
+   npmglobalize --force    # Proceeds despite detached HEAD
+   ```
+   Warning: Commits may be hard to track later. Consider merging back to a branch afterward.
+
 ## Command Reference
 
 ### Release Options

package/lib.js

@@ -1276,11 +1276,58 @@ export async function globalize(cwd, options = {}) {
         return false;
     }
     if (currentGitStatus.isDetachedHead && !force) {
-        console.error(colors.red('ERROR: Detached HEAD state. Use --force to continue anyway.'));
-        return false;
+        if (conform && !noPublish) {
+            // Conform already happened earlier, just exit gracefully
+            console.log('');
+            console.log(colors.green('✓ Files have been updated successfully!'));
+            console.log('  • .gitignore updated');
+            console.log('  • .npmignore updated');
+            console.log('  • .gitattributes created/updated (LF line endings)');
+            console.log('  • Git configured: core.autocrlf=false, core.eol=lf');
+            console.log('');
+            console.log(colors.yellow('ℹ What is "Detached HEAD"?'));
+            console.log('  Your git repository is not on a branch (master, main, etc.)');
+            console.log('  This happens after checking out a specific commit or tag.');
+            console.log('  Publishing requires being on a branch so git can track changes.');
+            console.log('');
+            console.log(colors.yellow('✓ Good news: Your files are already fixed!'));
+            console.log(colors.yellow('  You don\'t need to run --conform again.'));
+            console.log('');
+            console.log(colors.yellow('To publish, get back on a branch:'));
+            console.log('  git checkout master       \x1b[2m# or whatever your branch is\x1b[0m');
+            console.log('  npmglobalize              \x1b[2m# will now work normally\x1b[0m');
+            console.log('');
+            return true; // Success - conform was completed
+        }
+        else if (noPublish) {
+            // Just doing non-publish operations, detached HEAD is fine
+            console.log(colors.yellow('Note: Detached HEAD state (no publishing will occur)'));
+        }
+        else {
+            console.log('');
+            console.error(colors.red('ERROR: Cannot publish from Detached HEAD state'));
+            console.log('');
+            console.log(colors.yellow('ℹ What is "Detached HEAD"?'));
+            console.log('  Your git repository is not on a branch (master, main, etc.)');
+            console.log('  This happens after checking out a specific commit or tag.');
+            console.log('  Publishing requires being on a branch so git can track changes.');
+            console.log('');
+            console.log(colors.yellow('To fix this:'));
+            console.log('  git checkout master       \x1b[2m# or whatever your branch is\x1b[0m');
+            console.log('  npmglobalize              \x1b[2m# will now work\x1b[0m');
+            console.log('');
+            console.log(colors.yellow('Or to force publish anyway (risky):'));
+            console.log('  npmglobalize --force      \x1b[2m# proceeds despite detached HEAD\x1b[0m');
+            console.log('');
+            return false;
+        }
     }
     if (currentGitStatus.isDetachedHead && force) {
-        console.log(colors.yellow('Warning: Detached HEAD state - continuing with --force'));
+        console.log('');
+        console.log(colors.yellow('⚠ Warning: Publishing from Detached HEAD state (--force)'));
+        console.log('  This means you\'re not on a branch. The published commits may be');
+        console.log('  hard to track. Consider: git checkout master && git merge HEAD');
+        console.log('');
     }
     // Check if local branch is behind remote
     if (currentGitStatus.isBehindRemote && !dryRun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobfrankston/npmglobalize",
-  "version": "1.0.35",
+  "version": "1.0.36",
   "description": "Transform file: dependencies to npm versions for publishing",
   "main": "index.js",
   "type": "module",