worktree-add 1.3.0 → 1.3.1

package/README.md

@@ -12,7 +12,8 @@ Running `worktree-add <branch>` from inside a repo:
 4. If the destination exists, pass `--interactive` to be prompted for confirmation, or `--yes` to move it to the system trash without prompting. Without either flag, the command exits.
 5. Fetches `origin/<branch>` and refreshes your local branch when safe:
    - fast-forwards the local branch if it’s strictly behind `origin/<branch>`
-   - warns and keeps the local branch as-is if it’s ahead/diverged
+   - warns and keeps the local branch as-is if it’s ahead
+   - exits with recovery steps if local and remote have diverged
 6. Creates a git worktree:
    - reuses an existing local branch
    - or creates a tracking branch from `origin/<branch>`

package/dist/cli/run-worktree-add.js

@@ -10,6 +10,7 @@ import { cleanupWorktree } from "./cleanup-worktree.js";
 import { openWorktreeApps } from "./open-worktree-apps.js";
 import { registerSigintHandler } from "./register-sigint-handler.js";
 import { resolveWorktreeContext } from "./resolve-worktree-context.js";
+const quoteForShell = (value) => `'${value.replaceAll("'", "'\"'\"'")}'`;
 export async function runWorktreeAdd(branchRaw, options) {
     const dryRun = options.dryRun ?? false;
     const verbose = options.verbose ?? false;
@@ -66,6 +67,25 @@ export async function runWorktreeAdd(branchRaw, options) {
                 "Refusing to create a new branch from HEAD in this ambiguous state.\n" +
                 `Re-run with --offline to force creating a new local '${context.branch}' from the current HEAD.`);
         }
+        if (remoteStatus.status === "diverged") {
+            const { ahead, behind } = remoteStatus.divergence;
+            const branchForShell = quoteForShell(context.branch);
+            const archivedBranchForShell = quoteForShell(`${context.branch}-old`);
+            exitWithMessage(`Local branch '${context.branch}' and origin/${context.branch} have diverged (ahead by ${ahead} and behind by ${behind}).\n` +
+                "This can mean either a stale local branch-name collision or legitimate local commits plus new remote commits.\n" +
+                "Refusing to reuse the local branch automatically.\n" +
+                "Note: commands below use POSIX shell quoting. On Windows cmd.exe/PowerShell, adapt quoting for your shell.\n" +
+                "If you want to keep local commits, use your local branch directly:\n" +
+                `  git worktree add -- <path> ${branchForShell}\n` +
+                `  # or merge/rebase '${context.branch}' with origin/${context.branch}, then retry.\n` +
+                "To work on the remote branch, run:\n" +
+                "  git fetch origin --prune\n" +
+                "  # if '<branch>-old' already exists, pick a different archive name.\n" +
+                `  git branch -m -- ${branchForShell} ${archivedBranchForShell}\n` +
+                "  # or delete the stale local branch instead:\n" +
+                `  # git branch -D -- ${branchForShell}\n` +
+                `  worktree-add -- ${branchForShell}`);
+        }
         // Only treat origin as existing when confirmed; "unknown" remains false.
         const remoteBranchExists = remoteStatus.status === "exists";
         createWorktree(context.branch, context.destinationDirectory, {

package/dist/git/fetch-remote-branch.d.ts

@@ -1,9 +1,21 @@
 import type { StatusLogger } from "../output/create-status-logger.js";
-export type RemoteBranchStatus = "exists" | "missing" | "unknown";
+type RemoteBranchStatus = "exists" | "missing" | "unknown" | "diverged";
+type BranchDivergence = {
+    ahead: number;
+    behind: number;
+};
+type NonDivergedRemoteBranchStatus = Exclude<RemoteBranchStatus, "diverged">;
+export type FetchRemoteBranchResult = {
+    status: "diverged";
+    localExists: true;
+    divergence: BranchDivergence;
+} | {
+    status: NonDivergedRemoteBranchStatus;
+    localExists: boolean;
+    divergence: undefined;
+};
 export declare function fetchRemoteBranch(branch: string, options?: {
     dryRun?: boolean;
     logger?: StatusLogger;
-}): {
-    status: RemoteBranchStatus;
-    localExists: boolean;
-};
+}): FetchRemoteBranchResult;
+export {};

package/dist/git/fetch-remote-branch.js

@@ -14,15 +14,17 @@ export function fetchRemoteBranch(branch, options) {
         catch (error) {
             const diagnostic = extractDiagnosticLine(error);
             logger.warn(`Failed to query origin for '${normalized}': ${diagnostic}. Using existing local branch. (If you expected a remote branch, double-check your network connection and branch name.)`);
-            return { status: "unknown", localExists };
+            return { status: "unknown", localExists, divergence: undefined };
+        }
+        if (!remoteExists) {
+            return { status: "missing", localExists, divergence: undefined };
         }
-        if (!remoteExists)
-            return { status: "missing", localExists };
         try {
             if (dryRun) {
                 logger.step(`Would fetch origin/${normalized}`);
                 logger.detail(`Dry run: local '${normalized}' may be fast-forwarded after fetch if it is behind origin/${normalized}.`);
-                return { status: "exists", localExists };
+                logger.detail("Dry run does not check local/remote divergence because it skips fetch; a real run may stop with a divergence error.");
+                return { status: "exists", localExists, divergence: undefined };
             }
             logger.step(`Fetching origin/${normalized} …`);
             fetchOriginBranch(normalized);
@@ -30,12 +32,12 @@ export function fetchRemoteBranch(branch, options) {
         catch (error) {
             const diagnostic = extractDiagnosticLine(error);
             logger.warn(`Failed to fetch origin/${normalized}: ${diagnostic}. Using existing local branch (origin status unknown).`);
-            return { status: "unknown", localExists };
+            return { status: "unknown", localExists, divergence: undefined };
         }
         const localHead = getLocalBranchHead(normalized);
         const remoteHead = getRemoteBranchHead(normalized);
         if (!localHead || !remoteHead || localHead === remoteHead) {
-            return { status: "exists", localExists };
+            return { status: "exists", localExists, divergence: undefined };
         }
         let counts;
         try {
@@ -44,7 +46,7 @@ export function fetchRemoteBranch(branch, options) {
         catch (error) {
             const diagnostic = extractDiagnosticLine(error);
             logger.warn(`Failed to compare local '${normalized}' with origin/${normalized}: ${diagnostic}. Using existing local branch as-is.`);
-            return { status: "exists", localExists };
+            return { status: "exists", localExists, divergence: undefined };
         }
         const { ahead, behind } = counts;
         if (ahead === 0 && behind > 0) {
@@ -53,27 +55,28 @@ export function fetchRemoteBranch(branch, options) {
             const activeWorktree = findWorktreeByBranchName(normalized);
             if (activeWorktree) {
                 logger.warn(`Local branch '${normalized}' is checked out in ${activeWorktree}; skipping fast-forward.`);
-                return { status: "exists", localExists };
+                return { status: "exists", localExists, divergence: undefined };
             }
             logger.detail(`Fast-forwarding '${normalized}' from ${localHead} to ${remoteHead}.`);
             logger.step(`Fast-forwarding local '${normalized}' to origin/${normalized} …`);
             git("branch", "-f", "--", normalized, `origin/${normalized}`);
-            return { status: "exists", localExists };
+            return { status: "exists", localExists, divergence: undefined };
         }
         if (ahead === 0 && behind === 0) {
             // Defensive: rev-list should report differences when heads differ,
             // but shallow/corrupted refs can yield 0/0 counts.
             logger.warn(`Local branch '${normalized}' differs from origin/${normalized}, but Git reports no ahead/behind differences. Using existing local branch; if you encounter issues, try re-cloning the repository.`);
-            return { status: "exists", localExists };
+            return { status: "exists", localExists, divergence: undefined };
+        }
+        if (ahead > 0 && behind > 0) {
+            return {
+                status: "diverged",
+                localExists,
+                divergence: { ahead, behind },
+            };
         }
-        const descriptors = [];
-        if (ahead > 0)
-            descriptors.push(`ahead by ${ahead}`);
-        if (behind > 0)
-            descriptors.push(`behind by ${behind}`);
-        const relationship = behind > 0 ? "has diverged from" : "is ahead of";
-        logger.warn(`Local branch '${normalized}' ${relationship} origin/${normalized} (${descriptors.join(" and ")}); using existing local branch as-is.`);
-        return { status: "exists", localExists };
+        logger.warn(`Local branch '${normalized}' is ahead of origin/${normalized} (ahead by ${ahead}); using existing local branch as-is.`);
+        return { status: "exists", localExists, divergence: undefined };
     }
     let remoteExists;
     try {
@@ -82,14 +85,15 @@ export function fetchRemoteBranch(branch, options) {
     catch (error) {
         const diagnostic = extractDiagnosticLine(error);
         logger.warn(`Failed to reach origin to check whether '${normalized}' exists: ${diagnostic}. (If you expected a remote branch, double-check your network connection and branch name.)`);
-        return { status: "unknown", localExists };
+        return { status: "unknown", localExists, divergence: undefined };
+    }
+    if (!remoteExists) {
+        return { status: "missing", localExists, divergence: undefined };
     }
-    if (!remoteExists)
-        return { status: "missing", localExists };
     try {
         if (dryRun) {
             logger.step(`Would fetch origin/${normalized}`);
-            return { status: "exists", localExists };
+            return { status: "exists", localExists, divergence: undefined };
         }
         logger.step(`Fetching origin/${normalized} …`);
         fetchOriginBranch(normalized);
@@ -98,5 +102,5 @@ export function fetchRemoteBranch(branch, options) {
         const diagnostic = extractDiagnosticLine(error);
         throw new Error(`Failed to fetch origin/${normalized}: ${diagnostic}. Cannot proceed without a local branch.`);
     }
-    return { status: "exists", localExists };
+    return { status: "exists", localExists, divergence: undefined };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "worktree-add",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Create a Git worktree next to your current repo for a branch, copy useful local files, install deps, and open it in your apps.",
   "repository": {
     "type": "git",