shadow-git 0.1.0 → 1.0.2

package/package.json

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

package/src/cli.ts

@@ -2,31 +2,57 @@ import { Command } from 'commander';
 import { findRoot, validateShadowRepo } from './core/repository.js';
 import { forwardToGit } from './commands/forward.js';
 import { registerTrackCommands } from './commands/track/index.js';
+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 * as logger from './utils/logger.js';
 
+const COMMANDER_COMMANDS = new Set(['track', 'debug']);
+
 async function run(): Promise<void> {
   const args = process.argv.slice(2);
 
-  if (
-    args.length === 0 ||
-    args[0] === 'track' ||
-    args[0].startsWith('-')
-  ) {
-    const program = new Command('sgit')
-      .description('Shadow Git — a secondary git repository for your project')
-      .version('0.1.0');
+  // Skip guard for commands that manage gitignores themselves
+  const skipGuard =
+    (args[0] === 'track' && (args[1] === 'init' || args[1] === 'clone')) || args[0] === 'debug';
+
+  // Set up gitignore guard
+  let guardCleanup: (() => void) | undefined;
+  if (!skipGuard) {
+    try {
+      const root = await findRoot();
+      const manifest = await readManifest(root);
+      guardCleanup = setupGitignoreGuard(root, manifest.paths);
+    } catch {
+      // No git repo, no .sgit, or no manifest — proceed without guard
+    }
+  }
 
-    registerTrackCommands(program);
+  try {
+    if (
+      args.length === 0 ||
+      COMMANDER_COMMANDS.has(args[0]) ||
+      args[0].startsWith('-')
+    ) {
+      const program = new Command('sgit')
+        .description('Shadow Git — a secondary git repository for your project')
+        .version('0.1.0');
 
-    program.addHelpText(
-      'after',
-      `
+      registerTrackCommands(program);
+      registerDebugCommands(program);
+
+      program.addHelpText(
+        'after',
+        `
 Track commands:
   sgit track init          Initialize shadow repository
+  sgit track clone         Clone shadow repository from remote URL
   sgit track add           Start shadow-tracking paths (--adopt to move from main git)
   sgit track remove        Stop shadow-tracking paths
   sgit track list          List all shadow-tracked paths
+  sgit track ignore        Ignore paths within tracked directories
+  sgit track unignore      Stop ignoring paths
   sgit track sync          Regenerate exclude files
   sgit track verify        Validate staged files
   sgit track destroy       Remove shadow repository
@@ -34,14 +60,19 @@ Track commands:
 
 All other commands are forwarded to git in the shadow repository:
   sgit status, sgit commit, sgit log, sgit diff, ...`,
-    );
+      );
 
-    await program.parseAsync(process.argv);
-  } else {
-    const root = await findRoot();
-    await validateShadowRepo(root);
-    const exitCode = forwardToGit(root, args);
-    process.exit(exitCode);
+      await program.parseAsync(process.argv);
+    } else {
+      const root = await findRoot();
+      await validateShadowRepo(root);
+      const exitCode = forwardToGit(root, args);
+      guardCleanup?.();
+      guardCleanup = undefined;
+      process.exit(exitCode);
+    }
+  } finally {
+    guardCleanup?.();
   }
 }
 

package/src/commands/debug/gitignores.ts

@@ -0,0 +1,28 @@
+import { findRoot, validateShadowRepo } from '../../core/repository.js';
+import { readManifest } from '../../core/manifest.js';
+import { setupGitignoreGuard } from '../../core/gitignore.js';
+import * as logger from '../../utils/logger.js';
+
+export async function debugGitignores(): Promise<void> {
+  const root = await findRoot();
+  await validateShadowRepo(root);
+  const manifest = await readManifest(root);
+
+  const cleanup = setupGitignoreGuard(root, manifest.paths);
+
+  try {
+    logger.info('gitignores disabled — waiting 10 seconds…');
+    for (let i = 10; i > 0; i--) {
+      process.stdout.write(`\r  ${i}s remaining `);
+      await sleep(1000);
+    }
+    process.stdout.write('\r                \r');
+    logger.success('re-enabling gitignores');
+  } finally {
+    cleanup();
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/commands/debug/index.ts

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+import { SgitError } from '../../core/errors.js';
+import * as logger from '../../utils/logger.js';
+import { debugGitignores } from './gitignores.js';
+
+export function registerDebugCommands(program: Command): void {
+  const debug = new Command('debug')
+    .description('Debug utilities');
+
+  debug
+    .command('gitignores')
+    .description('Disable .gitignore files for 10 seconds, then re-enable')
+    .action(wrapAction(debugGitignores));
+
+  program.addCommand(debug, { hidden: true });
+}
+
+function wrapAction(
+  fn: (...args: any[]) => Promise<void>,
+): (...args: any[]) => Promise<void> {
+  return async (...args: any[]) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      if (err instanceof SgitError) {
+        logger.error(err.message);
+        process.exit(1);
+      }
+      throw err;
+    }
+  };
+}

package/src/commands/track/add.ts

@@ -9,9 +9,12 @@ import { syncExcludes } from './sync.js';
 import {
   PathNotFoundError,
   PathTrackedByMainError,
+  SgitError,
 } from '../../core/errors.js';
 import * as logger from '../../utils/logger.js';
 
+const BLOCKED_BASENAMES = new Set(['.gitignore', '.gitignore-sgit.bat']);
+
 export async function trackAdd(paths: string[], opts: { adopt?: boolean } = {}): Promise<void> {
   const root = await findRoot();
   await validateShadowRepo(root);
@@ -22,6 +25,14 @@ export async function trackAdd(paths: string[], opts: { adopt?: boolean } = {}):
   for (const inputPath of paths) {
     const normalized = await normalizePath(inputPath, root);
 
+    // .gitignore files are managed by sgit and cannot be tracked
+    const basename = normalized.split('/').pop() ?? '';
+    if (BLOCKED_BASENAMES.has(basename)) {
+      throw new SgitError(
+        `cannot track ${normalized}: .gitignore files are managed by sgit and cannot be tracked directly`,
+      );
+    }
+
     // Must exist on disk
     const checkPath = normalized.endsWith('/')
       ? normalized.slice(0, -1)

package/src/commands/track/clone.ts

@@ -0,0 +1,213 @@
+import { join, extname } from 'node:path';
+import { access, readFile, writeFile, rename, mkdir, rm } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { randomBytes } from 'node:crypto';
+import {
+  findRoot,
+  validateNotWorktree,
+  validateNotSubmodule,
+  validateGitIdentity,
+} from '../../core/repository.js';
+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 type { Manifest } from '../../core/manifest.js';
+import * as logger from '../../utils/logger.js';
+
+export async function trackClone(
+  url: string,
+  opts: { onConflict?: 1 | 2 | 3 } = {},
+): Promise<void> {
+  const root = await findRoot();
+  await validateNotWorktree(root);
+  await validateNotSubmodule(root);
+  await validateGitIdentity(root);
+
+  const sgitDir = join(root, '.sgit');
+
+  // Check if already initialized
+  try {
+    await access(sgitDir, constants.F_OK);
+    throw new AlreadyInitializedError();
+  } catch (err) {
+    if (err instanceof AlreadyInitializedError) throw err;
+    // Not found — continue
+  }
+
+  // Clone bare
+  try {
+    await execGit(['clone', '--bare', url, sgitDir]);
+  } catch {
+    // Clean up partial clone
+    try { await rm(sgitDir, { recursive: true, force: true }); } catch { /* best effort */ }
+    throw new SgitError(`failed to clone from ${url}`);
+  }
+
+  // Configure as non-bare with worktree
+  await execGit(['config', 'core.bare', 'false'], { gitDir: sgitDir });
+  await execGit(['config', 'core.worktree', root], { gitDir: sgitDir });
+
+  // Copy user identity from main repo
+  try {
+    const name = await execGit(['config', 'user.name'], { cwd: root });
+    if (name) {
+      await execGit(['config', 'user.name', name], { gitDir: sgitDir });
+    }
+  } catch {
+    // Not configured in main repo
+  }
+  try {
+    const email = await execGit(['config', 'user.email'], { cwd: root });
+    if (email) {
+      await execGit(['config', 'user.email', email], { gitDir: sgitDir });
+    }
+  } catch {
+    // Not configured in main repo
+  }
+
+  // Read manifest from cloned repo
+  let manifest: Manifest;
+  try {
+    const manifestJson = await execGit(['show', 'HEAD:.sgit.json'], { gitDir: sgitDir });
+    manifest = JSON.parse(manifestJson) as Manifest;
+  } catch {
+    manifest = { paths: [], ignore: [] };
+  }
+
+  // Get list of tracked files
+  let trackedFiles: string[] = [];
+  try {
+    const output = await execGit(['ls-tree', '-r', '--name-only', 'HEAD'], { gitDir: sgitDir });
+    if (output.trim()) {
+      trackedFiles = output.trim().split('\n');
+    }
+  } catch {
+    // Empty repo — nothing to checkout
+  }
+
+  // Detect conflicts
+  const conflicts: string[] = [];
+  for (const file of trackedFiles) {
+    try {
+      await access(join(root, file), constants.F_OK);
+      conflicts.push(file);
+    } catch {
+      // No conflict
+    }
+  }
+
+  // Resolve conflicts
+  let choice: 1 | 2 | 3 = 1;
+  if (conflicts.length > 0) {
+    if (opts.onConflict) {
+      choice = opts.onConflict;
+    } else {
+      logger.warn(`${conflicts.length} file(s) already exist on disk:`);
+      for (const f of conflicts) {
+        logger.info(`  ${f}`);
+      }
+      choice = await promptConflictResolution();
+    }
+
+    if (choice === 2) {
+      // Save conflicting files before checkout
+      const savedContent = new Map<string, Buffer>();
+      for (const file of conflicts) {
+        savedContent.set(file, await readFile(join(root, file)));
+      }
+
+      // Checkout all files
+      if (trackedFiles.length > 0) {
+        await execGit(['checkout', 'HEAD', '--', '.'], { gitDir: sgitDir, workTree: root });
+      }
+
+      // Restore originals
+      for (const [file, content] of savedContent) {
+        await mkdir(join(root, file, '..'), { recursive: true });
+        await writeFile(join(root, file), content);
+      }
+    } else if (choice === 3) {
+      // Rename conflicting files
+      for (const file of conflicts) {
+        const renamed = generateOriginalName(file);
+        await rename(join(root, file), join(root, renamed));
+      }
+
+      // Checkout all files
+      if (trackedFiles.length > 0) {
+        await execGit(['checkout', 'HEAD', '--', '.'], { gitDir: sgitDir, workTree: root });
+      }
+    } else {
+      // Option 1: just checkout (overwrites)
+      if (trackedFiles.length > 0) {
+        await execGit(['checkout', 'HEAD', '--', '.'], { gitDir: sgitDir, workTree: root });
+      }
+    }
+  } else {
+    // No conflicts — checkout directly
+    if (trackedFiles.length > 0) {
+      await execGit(['checkout', 'HEAD', '--', '.'], { gitDir: sgitDir, workTree: root });
+    }
+  }
+
+  // Sync exclude files
+  await syncExcludes(root);
+
+  // Install hooks
+  await installMainHook(root);
+  await installShadowHook(sgitDir);
+  await installShadowSyncHooks(sgitDir);
+
+  // Success message
+  const fileCount = trackedFiles.filter(f => f !== '.sgit.json').length;
+  logger.success(`Shadow repository cloned from ${url}`);
+  logger.info(`  ${fileCount} file(s) checked out`);
+  if (conflicts.length > 0) {
+    switch (choice) {
+      case 1:
+        logger.info(`  ${conflicts.length} conflicting file(s) overwritten`);
+        break;
+      case 2:
+        logger.info(`  ${conflicts.length} local file(s) kept (shadow repo shows them as modified)`);
+        break;
+      case 3:
+        logger.info(`  ${conflicts.length} local file(s) renamed with -original~ suffix`);
+        break;
+    }
+  }
+}
+
+async function promptConflictResolution(): Promise<1 | 2 | 3> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    process.stdout.write('\nHow should conflicts be resolved?\n');
+    process.stdout.write('  1 - Keep sgit (overwrite local files)\n');
+    process.stdout.write('  2 - Keep originals (local files stay, sgit shows them as modified)\n');
+    process.stdout.write('  3 - Rename originals (add -original~ suffix, checkout sgit versions)\n');
+    rl.question('\nChoice [1/2/3]: ', (answer) => {
+      rl.close();
+      const num = parseInt(answer.trim(), 10);
+      if (num === 1 || num === 2 || num === 3) {
+        resolve(num as 1 | 2 | 3);
+      } else {
+        resolve(2); // Default to safest option
+      }
+    });
+  });
+}
+
+function generateOriginalName(filePath: string): string {
+  const suffix = randomBytes(2).toString('hex');
+  const ext = extname(filePath);
+  if (ext) {
+    const base = filePath.slice(0, filePath.length - ext.length);
+    return `${base}-original~${suffix}${ext}`;
+  }
+  return `${filePath}-original~${suffix}`;
+}

package/src/commands/track/completion.ts

@@ -11,7 +11,7 @@ _sgit() {
 
   if [[ \${words[1]} == "track" ]]; then
     if [[ $cword -eq 2 ]]; then
-      COMPREPLY=($(compgen -W "init add remove list sync verify destroy completion" -- "$cur"))
+      COMPREPLY=($(compgen -W "init clone add remove list sync verify ignore unignore destroy completion" -- "$cur"))
       return
     fi
 
@@ -24,24 +24,34 @@ _sgit() {
           _filedir
         fi
         ;;
+      clone)
+        ;;
       remove)
         local paths
         paths=$(sgit track list 2>/dev/null)
         COMPREPLY=($(compgen -W "$paths" -- "$cur"))
         ;;
+      ignore)
+        _filedir
+        ;;
+      unignore)
+        local ignored
+        ignored=$(python3 -c "import json; d=json.load(open('.sgit.json')); print(' '.join(d.get('ignore',[])))" 2>/dev/null)
+        COMPREPLY=($(compgen -W "$ignored" -- "$cur"))
+        ;;
       verify)
         COMPREPLY=($(compgen -W "--main --shadow" -- "$cur"))
         ;;
       destroy)
-        COMPREPLY=($(compgen -W "--force" -- "$cur"))
+        COMPREPLY=($(compgen -W "--force --keep-files" -- "$cur"))
         ;;
       completion)
         if [[ $prev == "--shell" ]]; then
           COMPREPLY=($(compgen -W "bash zsh fish" -- "$cur"))
-        elif [[ $cur == -* ]]; then
-          COMPREPLY=($(compgen -W "--shell" -- "$cur"))
+        elif [[ $cword -eq 3 ]]; then
+          COMPREPLY=($(compgen -W "install --shell" -- "$cur"))
         else
-          COMPREPLY=($(compgen -W "install" -- "$cur"))
+          COMPREPLY=($(compgen -W "--shell" -- "$cur"))
         fi
         ;;
     esac
@@ -75,11 +85,14 @@ _sgit_track() {
   local -a subcmds
   subcmds=(
     'init:Initialize shadow repository'
+    'clone:Clone shadow repository from remote URL'
     'add:Start shadow-tracking paths'
     'remove:Stop shadow-tracking paths'
     'list:List all shadow-tracked paths'
     'sync:Regenerate exclude files'
     'verify:Validate staged files'
+    'ignore:Ignore paths within tracked directories'
+    'unignore:Stop ignoring paths within tracked directories'
     'destroy:Remove shadow repository'
     'completion:Install shell completions'
   )
@@ -90,6 +103,9 @@ _sgit_track() {
   fi
 
   case "\${words[2]}" in
+    clone)
+      _arguments '1:url:'
+      ;;
     add)
       _arguments '--adopt[Move main-git-tracked files to shadow tracking]' '*:file:_files'
       ;;
@@ -98,11 +114,19 @@ _sgit_track() {
       paths=(\${(f)"$(sgit track list 2>/dev/null)"})
       _describe 'tracked path' paths
       ;;
+    ignore)
+      _files
+      ;;
+    unignore)
+      local -a ignored
+      ignored=(\${(f)"$(python3 -c "import json; d=json.load(open('.sgit.json')); print('\\\\n'.join(d.get('ignore',[])))" 2>/dev/null)"})
+      _describe 'ignored path' ignored
+      ;;
     verify)
       _arguments '--main[Check main repo]' '--shadow[Check shadow repo]'
       ;;
     destroy)
-      _arguments '--force[Skip confirmation]'
+      _arguments '--force[Skip confirmation]' '--keep-files[Keep tracked files on disk]'
       ;;
     completion)
       _arguments '--shell[Shell type]:shell:(bash zsh fish)' '1:action:(install)'
@@ -148,14 +172,18 @@ complete -c sgit -w git
 complete -c sgit -n '__fish_use_subcommand' -a track -d 'Manage shadow-tracked paths'
 
 # Track subcommands
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a init -d 'Initialize shadow repository'
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a add -d 'Start shadow-tracking paths'
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a remove -d 'Stop shadow-tracking paths'
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a list -d 'List all shadow-tracked paths'
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a sync -d 'Regenerate exclude files'
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a verify -d 'Validate staged files'
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a destroy -d 'Remove shadow repository'
-complete -c sgit -n '__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from init add remove list sync verify destroy completion' -a completion -d 'Install shell completions'
+set -l __sgit_track_cmds init clone add remove list sync verify ignore unignore destroy completion
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a init -d 'Initialize shadow repository'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a clone -d 'Clone shadow repository from remote URL'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a add -d 'Start shadow-tracking paths'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a remove -d 'Stop shadow-tracking paths'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a list -d 'List all shadow-tracked paths'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a sync -d 'Regenerate exclude files'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a verify -d 'Validate staged files'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a ignore -d 'Ignore paths within tracked directories'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a unignore -d 'Stop ignoring paths within tracked directories'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a destroy -d 'Remove shadow repository'
+complete -c sgit -n "__fish_seen_subcommand_from track; and not __fish_seen_subcommand_from \$__sgit_track_cmds" -a completion -d 'Install shell completions'
 
 # Track add options and file completions
 complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from add' -l adopt -d 'Move main-git-tracked files'
@@ -164,15 +192,22 @@ complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcomma
 # Track remove — complete from manifest
 complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from remove' -a '(sgit track list 2>/dev/null)'
 
+# Track ignore — file completions
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from ignore' -F
+
+# Track unignore — complete from .sgit.json ignore list
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from unignore' -a "(python3 -c \\"import json; d=json.load(open('.sgit.json')); print(' '.join(d.get('ignore',[])))\\\" 2>/dev/null)"
+
 # Track verify options
 complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from verify' -l main -d 'Check main repo'
 complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from verify' -l shadow -d 'Check shadow repo'
 
 # Track destroy options
 complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from destroy' -l force -d 'Skip confirmation'
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from destroy' -l keep-files -d 'Keep tracked files on disk'
 
 # Track completion options
-complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from completion' -a install -d 'Install completions'
+complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from completion; and not __fish_seen_subcommand_from install' -a install -d 'Install completions'
 complete -c sgit -n '__fish_seen_subcommand_from track; and __fish_seen_subcommand_from completion' -l shell -d 'Shell type' -ra 'bash zsh fish'
 `;
 }