shadow-git 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shadow-git",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "A secondary git repository for tracking files excluded from your main repo",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -6,6 +6,8 @@ import { registerDebugCommands } from './commands/debug/index.js';
 import { SgitError } from './core/errors.js';
 import { readManifest } from './core/manifest.js';
 import { setupGitignoreGuard } from './core/gitignore.js';
+import { isSwapMode, assertConsistentState } from './core/swap-mode.js';
+import { SwapModeCorruptError } from './core/errors.js';
 import * as logger from './utils/logger.js';
 
 const COMMANDER_COMMANDS = new Set(['track', 'debug']);
@@ -13,9 +15,37 @@ const COMMANDER_COMMANDS = new Set(['track', 'debug']);
 async function run(): Promise<void> {
   const args = process.argv.slice(2);
 
-  // Skip guard for commands that manage gitignores themselves
-  const skipGuard =
-    (args[0] === 'track' && (args[1] === 'init' || args[1] === 'clone')) || args[0] === 'debug';
+  // Detect swap mode (and surface any inconsistent state) up front
+  let swapActive = false;
+  try {
+    const root = await findRoot();
+    await assertConsistentState(root);
+    swapActive = await isSwapMode(root);
+  } catch (err) {
+    if (err instanceof SwapModeCorruptError) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+    // No git repo, no .sgit, etc. — proceed without swap-mode signals
+  }
+
+  // Suppress banner for the swap/unswap commands themselves — their own
+  // success messages already describe the state transition.
+  const suppressBanner =
+    args[0] === 'track' && (args[1] === 'swap' || args[1] === 'unswap');
+  if (swapActive && !suppressBanner) {
+    logger.swapModeBanner();
+  }
+
+  // Skip guard for commands that manage gitignores themselves, and whenever
+  // swap mode is active (gitignores are already disabled until unswap).
+  const selfManagedGuard =
+    args[0] === 'track' &&
+    (args[1] === 'init' ||
+      args[1] === 'clone' ||
+      args[1] === 'swap' ||
+      args[1] === 'unswap');
+  const skipGuard = selfManagedGuard || args[0] === 'debug' || swapActive;
 
   // Set up gitignore guard
   let guardCleanup: (() => void) | undefined;
@@ -55,6 +85,8 @@ Track commands:
   sgit track unignore      Stop ignoring paths
   sgit track sync          Regenerate exclude files
   sgit track verify        Validate staged files
+  sgit track swap          Swap .git with .sgit for IDE compatibility
+  sgit track unswap        Exit swap mode
   sgit track destroy       Remove shadow repository
   sgit track completion    Install shell completions
 
@@ -66,7 +98,7 @@ All other commands are forwarded to git in the shadow repository:
     } else {
       const root = await findRoot();
       await validateShadowRepo(root);
-      const exitCode = forwardToGit(root, args);
+      const exitCode = await forwardToGit(root, args);
       guardCleanup?.();
       guardCleanup = undefined;
       process.exit(exitCode);

package/src/commands/forward.ts

@@ -1,8 +1,8 @@
 import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
+import { resolveShadowDir } from '../core/swap-mode.js';
 
-export function forwardToGit(root: string, args: string[]): number {
-  const sgitDir = join(root, '.sgit');
+export async function forwardToGit(root: string, args: string[]): Promise<number> {
+  const sgitDir = await resolveShadowDir(root);
   const result = spawnSync(
     'git',
     [`--git-dir=${sgitDir}`, `--work-tree=${root}`, ...args],

package/src/commands/track/add.ts

@@ -11,14 +11,16 @@ import {
   PathTrackedByMainError,
   SgitError,
 } from '../../core/errors.js';
+import { resolveShadowDir, resolveMainDir } from '../../core/swap-mode.js';
 import * as logger from '../../utils/logger.js';
 
-const BLOCKED_BASENAMES = new Set(['.gitignore', '.gitignore-sgit.bat']);
+const BLOCKED_BASENAMES = new Set(['.gitignore', '.gitignore.sgit-parked']);
 
 export async function trackAdd(paths: string[], opts: { adopt?: boolean } = {}): Promise<void> {
   const root = await findRoot();
   await validateShadowRepo(root);
-  const sgitDir = join(root, '.sgit');
+  const sgitDir = await resolveShadowDir(root);
+  const mainDir = await resolveMainDir(root);
 
   const added: string[] = [];
 
@@ -51,7 +53,7 @@ export async function trackAdd(paths: string[], opts: { adopt?: boolean } = {}):
     let trackedByMain = false;
     try {
       await execGit(['ls-files', '--error-unmatch', checkPath], {
-        gitDir: join(root, '.git'),
+        gitDir: mainDir,
         workTree: root,
       });
       trackedByMain = true;
@@ -64,7 +66,7 @@ export async function trackAdd(paths: string[], opts: { adopt?: boolean } = {}):
         const rmArgs = normalized.endsWith('/')
           ? ['rm', '--cached', '-r', checkPath]
           : ['rm', '--cached', checkPath];
-        await execGit(rmArgs, { gitDir: join(root, '.git'), workTree: root });
+        await execGit(rmArgs, { gitDir: mainDir, workTree: root });
       } else if (!opts.adopt) {
         throw new PathTrackedByMainError(normalized);
       }

package/src/commands/track/clone.ts

@@ -12,7 +12,8 @@ import {
 import { execGit } from '../../core/git.js';
 import { installMainHook, installShadowHook, installShadowSyncHooks } from '../../core/hooks.js';
 import { syncExcludes } from './sync.js';
-import { AlreadyInitializedError, SgitError } from '../../core/errors.js';
+import { AlreadyInitializedError, SwapModeActiveError, SgitError } from '../../core/errors.js';
+import { isSwapMode } from '../../core/swap-mode.js';
 import type { Manifest } from '../../core/manifest.js';
 import * as logger from '../../utils/logger.js';
 
@@ -21,6 +22,9 @@ export async function trackClone(
   opts: { onConflict?: 1 | 2 | 3 } = {},
 ): Promise<void> {
   const root = await findRoot();
+  if (await isSwapMode(root)) {
+    throw new SwapModeActiveError('clone');
+  }
   await validateNotWorktree(root);
   await validateNotSubmodule(root);
   await validateGitIdentity(root);
@@ -49,6 +53,17 @@ export async function trackClone(
   await execGit(['config', 'core.bare', 'false'], { gitDir: sgitDir });
   await execGit(['config', 'core.worktree', root], { gitDir: sgitDir });
 
+  // `git clone --bare` sets a mirror-style fetch refspec which is wrong for
+  // a working (non-bare) repo — overwrite with the normal refspec so that
+  // `sgit fetch` populates refs/remotes/origin/* and refs like `origin/main`
+  // resolve as expected.
+  await execGit(
+    ['config', 'remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*'],
+    { gitDir: sgitDir },
+  );
+  // Populate remote-tracking refs from the already-fetched objects.
+  await execGit(['fetch', 'origin'], { gitDir: sgitDir });
+
   // Copy user identity from main repo
   try {
     const name = await execGit(['config', 'user.name'], { cwd: root });

package/src/commands/track/destroy.ts

@@ -5,6 +5,8 @@ import { findRoot, validateShadowRepo } from '../../core/repository.js';
 import { uninstallMainHook } from '../../core/hooks.js';
 import { execGit } from '../../core/git.js';
 import { SGIT_BLOCK_START, SGIT_BLOCK_END } from '../../core/exclude.js';
+import { isSwapMode } from '../../core/swap-mode.js';
+import { SwapModeActiveError } from '../../core/errors.js';
 import * as logger from '../../utils/logger.js';
 
 export async function trackDestroy(opts: {
@@ -12,6 +14,9 @@ export async function trackDestroy(opts: {
   keepFiles?: boolean;
 }): Promise<void> {
   const root = await findRoot();
+  if (await isSwapMode(root)) {
+    throw new SwapModeActiveError('destroy');
+  }
   await validateShadowRepo(root);
   const sgitDir = join(root, '.sgit');
 

package/src/commands/track/ignore.ts

@@ -1,16 +1,16 @@
-import { join } from 'node:path';
 import { findRoot, validateShadowRepo } from '../../core/repository.js';
 import { execGit } from '../../core/git.js';
 import { normalizePath, isPathCoveredByManifest } from '../../core/paths.js';
 import { addIgnore, readManifest } from '../../core/manifest.js';
 import { syncExcludes } from './sync.js';
 import { PathNotTrackedError } from '../../core/errors.js';
+import { resolveShadowDir } from '../../core/swap-mode.js';
 import * as logger from '../../utils/logger.js';
 
 export async function trackIgnore(paths: string[]): Promise<void> {
   const root = await findRoot();
   await validateShadowRepo(root);
-  const sgitDir = join(root, '.sgit');
+  const sgitDir = await resolveShadowDir(root);
 
   const added: string[] = [];
 

package/src/commands/track/index.ts

@@ -12,6 +12,8 @@ import { trackDestroy } from './destroy.js';
 import { trackIgnore } from './ignore.js';
 import { trackUnignore } from './unignore.js';
 import { trackCompletion } from './completion.js';
+import { trackSwap } from './swap.js';
+import { trackUnswap } from './unswap.js';
 
 export function registerTrackCommands(program: Command): void {
   const track = program
@@ -94,6 +96,16 @@ export function registerTrackCommands(program: Command): void {
         trackCompletion(action, opts),
       ),
     );
+
+  track
+    .command('swap')
+    .description('Swap .git with .sgit so IDE tools see the shadow repo as the active git')
+    .action(wrapAction(trackSwap));
+
+  track
+    .command('unswap')
+    .description('Exit swap mode and restore the main repository')
+    .action(wrapAction(trackUnswap));
 }
 
 export function wrapAction(

package/src/commands/track/init.ts

@@ -14,11 +14,15 @@ import {
   generateShadowExclude,
 } from '../../core/exclude.js';
 import { installMainHook, installShadowHook, installShadowSyncHooks } from '../../core/hooks.js';
-import { AlreadyInitializedError } from '../../core/errors.js';
+import { AlreadyInitializedError, SwapModeActiveError } from '../../core/errors.js';
+import { isSwapMode } from '../../core/swap-mode.js';
 import * as logger from '../../utils/logger.js';
 
 export async function trackInit(): Promise<void> {
   const root = await findRoot();
+  if (await isSwapMode(root)) {
+    throw new SwapModeActiveError('init');
+  }
   await validateNotWorktree(root);
   await validateNotSubmodule(root);
   await validateGitIdentity(root);

package/src/commands/track/remove.ts

@@ -1,15 +1,16 @@
-import { join, resolve, relative, sep } from 'node:path';
+import { resolve, relative, sep } from 'node:path';
 import { findRoot, validateShadowRepo } from '../../core/repository.js';
 import { execGit } from '../../core/git.js';
 import { removePath, readManifest } from '../../core/manifest.js';
 import { syncExcludes } from './sync.js';
 import { PathNotTrackedError } from '../../core/errors.js';
+import { resolveShadowDir } from '../../core/swap-mode.js';
 import * as logger from '../../utils/logger.js';
 
 export async function trackRemove(paths: string[]): Promise<void> {
   const root = await findRoot();
   await validateShadowRepo(root);
-  const sgitDir = join(root, '.sgit');
+  const sgitDir = await resolveShadowDir(root);
 
   const removed: string[] = [];
 

package/src/commands/track/swap.ts

@@ -0,0 +1,61 @@
+import { join } from 'node:path';
+import { rename } from 'node:fs/promises';
+import { findRoot, validateShadowRepo } from '../../core/repository.js';
+import { readManifest } from '../../core/manifest.js';
+import {
+  disableGitignores,
+  enableGitignores,
+} from '../../core/gitignore.js';
+import {
+  isSwapMode,
+  assertNoInProgressOps,
+  SWAP_MARKER,
+} from '../../core/swap-mode.js';
+import { AlreadySwappedError } from '../../core/errors.js';
+import * as logger from '../../utils/logger.js';
+
+export async function trackSwap(): Promise<void> {
+  const root = await findRoot();
+  await validateShadowRepo(root);
+
+  if (await isSwapMode(root)) {
+    throw new AlreadySwappedError();
+  }
+
+  await assertNoInProgressOps(join(root, '.git'));
+
+  const manifest = await readManifest(root);
+  const gitPath = join(root, '.git');
+  const sgitPath = join(root, '.sgit');
+  const disabledPath = join(root, SWAP_MARKER);
+
+  // Disable gitignores first (they must stay disabled throughout swap mode)
+  disableGitignores(root, manifest.paths);
+
+  let gitRenamed = false;
+  try {
+    await rename(gitPath, disabledPath);
+    gitRenamed = true;
+    await rename(sgitPath, gitPath);
+  } catch (err) {
+    // Rollback: restore .git and re-enable gitignores
+    if (gitRenamed) {
+      try {
+        await rename(disabledPath, gitPath);
+      } catch {
+        // Leave as-is; user must recover manually
+      }
+    }
+    try {
+      enableGitignores(root, manifest.paths);
+    } catch {
+      // best effort
+    }
+    throw err;
+  }
+
+  logger.success(
+    'Swap mode enabled. .sgit is now .git; main git is parked at .git.sgit-parked.',
+  );
+  logger.info("Run 'sgit track unswap' to exit.");
+}

package/src/commands/track/sync.ts

@@ -7,28 +7,31 @@ import {
   generateMainExclude,
   generateShadowExclude,
 } from '../../core/exclude.js';
+import { resolveShadowDir, resolveMainDir } from '../../core/swap-mode.js';
 import * as logger from '../../utils/logger.js';
 
 export async function syncExcludes(root: string): Promise<void> {
   const manifest = await readManifest(root);
+  const mainDir = await resolveMainDir(root);
+  const shadowDir = await resolveShadowDir(root);
 
-  // Regenerate .git/info/exclude
-  const mainExcludePath = join(root, '.git', 'info', 'exclude');
+  // Regenerate <main>/info/exclude
+  const mainExcludePath = join(mainDir, 'info', 'exclude');
   let existingExclude = '';
   try {
     existingExclude = await readFile(mainExcludePath, 'utf-8');
   } catch {
     // File might not exist
   }
-  await mkdir(join(root, '.git', 'info'), { recursive: true });
+  await mkdir(join(mainDir, 'info'), { recursive: true });
   await writeFile(
     mainExcludePath,
     generateMainExclude(existingExclude, manifest.paths),
   );
 
-  // Regenerate .sgit/info/exclude
-  const sgitExcludePath = join(root, '.sgit', 'info', 'exclude');
-  await mkdir(join(root, '.sgit', 'info'), { recursive: true });
+  // Regenerate <shadow>/info/exclude
+  const sgitExcludePath = join(shadowDir, 'info', 'exclude');
+  await mkdir(join(shadowDir, 'info'), { recursive: true });
   await writeFile(sgitExcludePath, generateShadowExclude(manifest.paths, manifest.ignore));
 
   // Warn for missing paths

package/src/commands/track/unswap.ts

@@ -0,0 +1,49 @@
+import { join } from 'node:path';
+import { rename } from 'node:fs/promises';
+import { findRoot } from '../../core/repository.js';
+import { readManifest } from '../../core/manifest.js';
+import { enableGitignores } from '../../core/gitignore.js';
+import {
+  isSwapMode,
+  assertNoInProgressOps,
+  SWAP_MARKER,
+} from '../../core/swap-mode.js';
+import { NotSwappedError } from '../../core/errors.js';
+import * as logger from '../../utils/logger.js';
+
+export async function trackUnswap(): Promise<void> {
+  const root = await findRoot();
+
+  if (!(await isSwapMode(root))) {
+    throw new NotSwappedError();
+  }
+
+  const gitPath = join(root, '.git');
+  const sgitPath = join(root, '.sgit');
+  const disabledPath = join(root, SWAP_MARKER);
+
+  // In swap mode, .git is the shadow — make sure it's idle
+  await assertNoInProgressOps(gitPath);
+
+  let shadowRenamed = false;
+  try {
+    await rename(gitPath, sgitPath);
+    shadowRenamed = true;
+    await rename(disabledPath, gitPath);
+  } catch (err) {
+    if (shadowRenamed) {
+      try {
+        await rename(sgitPath, gitPath);
+      } catch {
+        // Leave for manual recovery
+      }
+    }
+    throw err;
+  }
+
+  // Re-enable gitignores using the now-restored manifest
+  const manifest = await readManifest(root);
+  enableGitignores(root, manifest.paths);
+
+  logger.success('Swap mode disabled. Main git restored.');
+}

package/src/commands/track/verify.ts

@@ -1,10 +1,10 @@
-import { join } from 'node:path';
 import { findRoot, validateShadowRepo } from '../../core/repository.js';
 import { execGit } from '../../core/git.js';
 import { readManifest } from '../../core/manifest.js';
 import { isPathCoveredByManifest } from '../../core/paths.js';
 import { findStaleGitignores, isGuardActive } from '../../core/gitignore.js';
 import { SgitError } from '../../core/errors.js';
+import { resolveShadowDir, resolveMainDir, isSwapMode } from '../../core/swap-mode.js';
 import * as logger from '../../utils/logger.js';
 
 export interface VerifyResult {
@@ -16,12 +16,13 @@ export async function verifyMain(root: string): Promise<VerifyResult> {
   const manifest = await readManifest(root);
   const violations: string[] = [];
 
-  // Check for stale .gitignore-sgit.bat (skip if a guard is active)
-  if (!isGuardActive(root)) {
+  // Skip stale check when guard is active (normal command in flight) or
+  // when swap mode is active (gitignores are intentionally disabled).
+  if (!isGuardActive(root) && !(await isSwapMode(root))) {
     const stale = findStaleGitignores(root, manifest.paths);
     violations.push(
       ...stale.map(
-        (f) => `${f} (stale .gitignore-sgit.bat — rename back to .gitignore)`,
+        (f) => `${f} (stale .gitignore.sgit-parked — rename back to .gitignore)`,
       ),
     );
   }
@@ -30,7 +31,7 @@ export async function verifyMain(root: string): Promise<VerifyResult> {
   // a shadow-tracked file from main git is correct behavior)
   try {
     const staged = await execGit(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], {
-      gitDir: join(root, '.git'),
+      gitDir: await resolveMainDir(root),
       workTree: root,
     });
     if (staged.trim()) {
@@ -57,15 +58,16 @@ export async function verifyShadow(root: string): Promise<VerifyResult> {
       violations: ['.sgit.json (missing or invalid on disk)'],
     };
   }
-  const sgitDir = join(root, '.sgit');
+  const sgitDir = await resolveShadowDir(root);
   const violations: string[] = [];
 
-  // Check for stale .gitignore-sgit.bat (skip if a guard is active)
-  if (!isGuardActive(root)) {
+  // Skip stale check when guard is active (normal command in flight) or
+  // when swap mode is active (gitignores are intentionally disabled).
+  if (!isGuardActive(root) && !(await isSwapMode(root))) {
     const stale = findStaleGitignores(root, manifest.paths);
     violations.push(
       ...stale.map(
-        (f) => `${f} (stale .gitignore-sgit.bat — rename back to .gitignore)`,
+        (f) => `${f} (stale .gitignore.sgit-parked — rename back to .gitignore)`,
       ),
     );
   }

package/src/core/errors.ts

@@ -53,7 +53,7 @@ export class StaleGitignoreError extends SgitError {
   constructor(files: string[]) {
     super(
       [
-        'found stale .gitignore-sgit.bat files (a previous sgit command did not complete cleanly):',
+        'found stale .gitignore.sgit-parked files (a previous sgit command did not complete cleanly):',
         ...files.map((f) => `  ${f}`),
         '',
         'rename them back to .gitignore manually, then retry.',
@@ -61,3 +61,33 @@ export class StaleGitignoreError extends SgitError {
     );
   }
 }
+
+export class AlreadySwappedError extends SgitError {
+  constructor() {
+    super("shadow-git is already in swap mode; run 'sgit track unswap' to exit.");
+  }
+}
+
+export class NotSwappedError extends SgitError {
+  constructor() {
+    super('shadow-git is not in swap mode.');
+  }
+}
+
+export class SwapModeActiveError extends SgitError {
+  constructor(op: string) {
+    super(`cannot ${op} while in swap mode; run 'sgit track unswap' first.`);
+  }
+}
+
+export class SwapModeCorruptError extends SgitError {
+  constructor(details: string) {
+    super(`shadow-git state is inconsistent:\n${details}`);
+  }
+}
+
+export class InProgressGitOpError extends SgitError {
+  constructor(gitDir: string, marker: string) {
+    super(`cannot proceed: ${gitDir} has an in-progress operation (${marker}). Finish or abort it first.`);
+  }
+}

package/src/core/exclude.ts

@@ -32,7 +32,7 @@ export function generateMainExclude(
     preserved.pop();
   }
 
-  const sgitEntries = ['.sgit', '.sgit.json', '.gitignore-sgit.bat', ...manifestPaths];
+  const sgitEntries = ['.sgit', '.sgit.json', '.git.sgit-parked', '.gitignore.sgit-parked', ...manifestPaths];
 
   return [
     ...preserved,
@@ -85,7 +85,7 @@ export function generateShadowExclude(manifestPaths: string[], ignorePaths: stri
     '!.sgit.json',
     ...entryLines,
     ...ignorePaths,
-    '.gitignore-sgit.bat',
+    '.gitignore.sgit-parked',
     SGIT_BLOCK_END,
   ].join('\n') + '\n';
 }

package/src/core/gitignore.ts

@@ -7,18 +7,31 @@ import {
   unlinkSync,
 } from 'node:fs';
 import { join, relative, sep } from 'node:path';
-import { StaleGitignoreError } from './errors.js';
+import { StaleGitignoreError, SwapModeActiveError } from './errors.js';
+import { isSwapModeSync } from './swap-mode.js';
 import * as logger from '../utils/logger.js';
 
-const DISABLED_NAME = '.gitignore-sgit.bat';
+const DISABLED_NAME = '.gitignore.sgit-parked';
 const LOCK_FILE = '.gitignore-guard';
 
+// Refuse to touch gitignore state while swap mode is active — swap/unswap are
+// the only commands that transition this state, and they call these helpers
+// outside the swap window (swap before the marker exists, unswap after it is
+// removed). Any other caller (CLI guard, debug gitignores, ad-hoc use) would
+// de-sync the invariant documented in CLAUDE.md.
+function refuseIfSwapped(root: string, op: string): void {
+  if (isSwapModeSync(root)) {
+    throw new SwapModeActiveError(op);
+  }
+}
+
 // --- Public API ---
 
 export function disableGitignores(
   root: string,
   manifestPaths: string[],
 ): string[] {
+  refuseIfSwapped(root, 'disable gitignores');
   const gitignores = findInTrackedDirs(root, manifestPaths, '.gitignore');
   if (gitignores.length === 0) return [];
 
@@ -41,6 +54,7 @@ export function enableGitignores(
   root: string,
   manifestPaths: string[],
 ): string[] {
+  refuseIfSwapped(root, 'enable gitignores');
   const disabled = findInTrackedDirs(root, manifestPaths, DISABLED_NAME);
   const enabled: string[] = [];
   for (const relPath of disabled) {
@@ -77,6 +91,7 @@ export function setupGitignoreGuard(
   root: string,
   manifestPaths: string[],
 ): () => void {
+  refuseIfSwapped(root, 'set up gitignore guard');
   const lockPath = join(root, '.sgit', LOCK_FILE);
 
   // Nested invocation — another sgit process owns the guard
@@ -88,7 +103,7 @@ export function setupGitignoreGuard(
   const stale = findInTrackedDirs(root, manifestPaths, DISABLED_NAME);
   if (stale.length > 0) {
     logger.warn(
-      'found stale .gitignore-sgit.bat files from a previous crash; restoring',
+      'found stale .gitignore.sgit-parked files from a previous crash; restoring',
     );
     enableGitignores(root, manifestPaths);
   }

package/src/core/repository.ts

@@ -28,8 +28,16 @@ export async function validateGitIdentity(root: string): Promise<void> {
 }
 
 export async function validateShadowRepo(root: string): Promise<void> {
+  // In swap mode, .sgit is renamed to .git and the marker .git.sgit-parked exists
   try {
     await access(join(root, '.sgit'), constants.F_OK);
+    return;
+  } catch {
+    // fall through
+  }
+  try {
+    await access(join(root, '.git.sgit-parked'), constants.F_OK);
+    return;
   } catch {
     throw new NotInitializedError();
   }