git-dedup-core 0.1.0 → 2.0.0

package/dist/index.js

@@ -5,7 +5,7 @@ import { access, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from
 import { homedir, constants as osConstants } from 'node:os';
 import { basename, delimiter, dirname, join, resolve, sep } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
-function cacheFailureReason(error, stage) {
+function addFailureReason(error, stage) {
     const message = String(error);
     if (/cannot lock ref|reference already exists|case.insensitive|refname collision/i.test(message))
         return 'ref collision in the shared pool';
@@ -70,11 +70,27 @@ async function directorySize(path) {
 }
 const remoteId = (key) => createHash('sha256').update(key).digest('hex');
 function unsupportedClone(args) {
-    return args.some((arg) => /^(--depth|--shallow|--filter|--mirror|--bare|--reference|--dissociate|--no-hardlinks|--shared|--separate-git-dir|--bundle-uri|--sparse|--upload-pack|--server-option|--template|--config|--origin|--no-checkout|--single-branch|--no-single-branch|--revision|--jobs|-j|-o|-u|-c)(=|$)/.test(arg));
+    return args.find((arg) => /^(--depth|--shallow|--filter|--mirror|--bare|--reference|--dissociate|--no-hardlinks|--shared|--separate-git-dir|--bundle-uri|--sparse|--upload-pack|--server-option|--template|--config|--origin|--no-checkout|--single-branch|--no-single-branch|--revision|--jobs|-j|-o|-u|-c)(=|$)/.test(arg));
 }
+/** Reports a handled command that is forwarded to plain Git, unless Git was asked to be quiet. */
+function fallback(args, reason) {
+    if (!args.includes('-q') && !args.includes('--quiet'))
+        process.stderr.write(`git-dedup: ${reason}; using plain Git\n`);
+    return undefined;
+}
+/** The last Git `fatal:` or `error:` line of a failure, without captured progress output. */
+function gitFailure(error) {
+    const line = String(error)
+        .match(/\b(?:fatal|error): [^\r\n]*/g)
+        ?.at(-1)
+        ?.trim();
+    return line ? ` (${line})` : '';
+}
+/** Returns the parsed clone, or the reason git-dedup cannot handle it. */
 function parseClone(args) {
-    if (unsupportedClone(args))
-        return undefined;
+    const unsupported = unsupportedClone(args);
+    if (unsupported)
+        return `clone option ${unsupported.split('=')[0]} is not supported`;
     const positional = [];
     let recurse = false;
     let branch;
@@ -88,7 +104,7 @@ function parseClone(args) {
         if (arg === '-b' || arg === '--branch') {
             branch = args[++i];
             if (!branch)
-                return undefined;
+                return `clone option ${arg} requires a value`;
             forwarded.push(arg, branch);
             continue;
         }
@@ -107,11 +123,11 @@ function parseClone(args) {
             continue;
         }
         if (arg.startsWith('-'))
-            return undefined;
+            return `clone option ${arg.split('=')[0]} is not supported`;
         positional.push(arg);
     }
     if (positional.length < 1 || positional.length > 2)
-        return undefined;
+        return 'clone expects a repository and an optional directory';
     return { remote: positional[0], destination: positional[1], recurse, branch, forwarded };
 }
 function defaultCloneName(remote) {
@@ -121,6 +137,24 @@ function defaultCloneName(remote) {
         .at(-1)
         .replace(/\.git$/, '');
 }
+function submoduleAddPath(args) {
+    const positional = [];
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--') {
+            positional.push(...args.slice(i + 1));
+            break;
+        }
+        // Options of `git submodule add` that take a separate value.
+        if (['-b', '--branch', '--reference', '--ref-format', '--name', '--depth'].includes(arg))
+            i++;
+        else if (!arg.startsWith('-'))
+            positional.push(arg);
+    }
+    if (positional.length === 1)
+        return defaultCloneName(positional[0]);
+    return positional.length === 2 ? positional[1] : undefined;
+}
 function resolveSubmoduleRemote(parent, child) {
     if (!child.startsWith('./') && !child.startsWith('../'))
         return child;
@@ -189,6 +223,7 @@ async function canonicalPath(path) {
 }
 async function lockDirectory(lock, action) {
     await mkdir(dirname(lock), { recursive: true });
+    let ownerless = 0;
     for (let attempts = 0;; attempts++) {
         try {
             await mkdir(lock);
@@ -198,14 +233,16 @@ async function lockDirectory(lock, action) {
         catch (error) {
             if (error.code !== 'EEXIST')
                 throw error;
-            if (attempts > 1200)
-                throw new Error(`Timed out waiting for git-dedup lock: ${lock}`, { cause: error });
             if (attempts === 20)
                 process.stderr.write('git-dedup: waiting for the object pool lock\n');
             const owner = Number((await readFile(join(lock, 'owner'), 'utf8').catch(() => '')).trim());
+            const alive = owner > 0 && processExists(owner);
+            // Wait as long as a live owner holds the lock; only an ownerless lock times out.
+            if (!alive && ++ownerless > 1200)
+                throw new Error(`Timed out waiting for git-dedup lock: ${lock}`, { cause: error });
             const age = Date.now() - (await stat(lock).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
             // A dead owner may be reaped. A live but slow Git process must never lose its lock.
-            if (age > 5000 && owner && !processExists(owner)) {
+            if (age > 5000 && owner && !alive) {
                 await rm(lock, { recursive: true, force: true });
                 continue;
             }
@@ -255,10 +292,54 @@ async function withLock(root, action) {
 function poolPath(root) {
     return join(root, 'pool.git');
 }
+// Keep URL credentials out of the store; Git credential helpers supply them at fetch time.
+// HTTP(S) userinfo is a credential. Other schemes keep the user name, which SSH needs.
+function redactRemote(remote, mask = '') {
+    return remote.replace(/^([a-z][a-z0-9+.-]*:\/\/)([^/?#]*)@/i, (authority, scheme, userinfo) => {
+        const user = /^https?:/i.test(scheme) ? '' : userinfo.split(':')[0];
+        if (user === userinfo)
+            return authority;
+        const kept = user + (mask && (user ? ':' : '') + mask);
+        return scheme + (kept && `${kept}@`);
+    });
+}
+function registration(remote, key) {
+    return JSON.stringify({ key, remote: redactRemote(remote) }) + '\n';
+}
 async function registerRemote(root, remote, key) {
     const id = remoteId(key);
     await mkdir(join(root, 'remotes'), { recursive: true });
-    await writeFile(join(root, 'remotes', `${id}.json`), JSON.stringify({ key, remote }) + '\n');
+    await writeFile(join(root, 'remotes', `${id}.json`), registration(remote, key));
+}
+async function registerConsumer(root, id, gitdir) {
+    await mkdir(join(root, 'consumers'), { recursive: true });
+    await writeFile(join(root, 'consumers', `${id}.json`), JSON.stringify({ gitdir }) + '\n');
+}
+async function registeredConsumers(root) {
+    const consumers = new Map();
+    for (const name of await readdir(join(root, 'consumers')).catch(() => [])) {
+        const value = JSON.parse(await readFile(join(root, 'consumers', name), 'utf8'));
+        const id = name.replace(/\.json$/, '');
+        if (!/^[a-f0-9-]{36}$/.test(id) ||
+            !value ||
+            typeof value !== 'object' ||
+            !('gitdir' in value) ||
+            typeof value.gitdir !== 'string')
+            throw new Error(`Invalid git-dedup consumer registration: ${name}`);
+        consumers.set(id, value.gitdir);
+    }
+    return consumers;
+}
+async function carriesConsumerId(gitdir, id) {
+    const current = await readFile(join(gitdir, 'gitx-consumer-id'), 'utf8').catch((error) => {
+        if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+            return '';
+        throw error;
+    });
+    return current.trim() === id;
+}
+function checkoutPath(gitdir) {
+    return basename(gitdir) === '.git' ? dirname(gitdir) : gitdir;
 }
 async function setAlternate(gitdir, pool) {
     const alternate = join(gitdir, 'objects', 'info', 'alternates');
@@ -297,6 +378,8 @@ async function consumerId(commonGitdir) {
     }
 }
 export function createGitDedup(options = {}) {
+    if (process.platform === 'win32')
+        throw new Error('git-dedup does not support Windows yet. Run it inside WSL, or use Git directly. See https://github.com/bhouston/git-dedup/issues/74');
     const cwd = resolve(options.cwd ?? process.cwd());
     const incomingEnv = { ...process.env, ...options.env };
     const env = { ...incomingEnv, GITX_ACTIVE: '1', GIT_DEDUP_ACTIVE: '1' };
@@ -346,18 +429,26 @@ export function createGitDedup(options = {}) {
         await access(candidate, constants.X_OK);
         return (cachedGit = candidate);
     }
-    async function git(args, at = cwd, inherit = false) {
+    // 'tee' captures output like the default and also streams stderr (Git progress) to the user.
+    async function git(args, at = cwd, inherit = false, input) {
         const binary = await gitPath();
         return new Promise((resolveResult, reject) => {
-            const child = spawn(binary, args, { cwd: at, env, stdio: inherit ? 'inherit' : ['ignore', 'pipe', 'pipe'] });
+            const child = spawn(binary, args, {
+                cwd: at,
+                env,
+                stdio: inherit === true ? 'inherit' : [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+            });
+            child.stdin?.end(input);
             let stdout = '';
             let stderr = '';
-            if (!inherit) {
+            if (inherit !== true) {
                 child.stdout?.on('data', (b) => {
                     stdout += b;
                 });
                 child.stderr?.on('data', (b) => {
                     stderr += b;
+                    if (inherit === 'tee')
+                        process.stderr.write(b);
                 });
             }
             const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
@@ -365,10 +456,10 @@ export function createGitDedup(options = {}) {
                 child.kill(signal);
             });
             const cleanup = () => {
-                if (inherit)
+                if (inherit === true)
                     signals.forEach((signal, i) => process.removeListener(signal, handlers[i]));
             };
-            if (inherit)
+            if (inherit === true)
                 signals.forEach((signal, i) => process.on(signal, handlers[i]));
             child.on('error', (error) => {
                 cleanup();
@@ -380,10 +471,10 @@ export function createGitDedup(options = {}) {
             });
         });
     }
-    async function checked(args, at = cwd) {
+    async function checked(args, at = cwd, progress = false, input) {
         if (hasRepositoryEnvironment)
             throw new Error('Unset Git repository override environment variables before running git-dedup storage operations');
-        const result = await git(args, at);
+        const result = await git(args, at, progress && 'tee', input);
         if (result.code !== 0)
             throw new Error(`git ${args.join(' ')} failed: ${result.stderr.trim()}`);
         return result.stdout.trim();
@@ -394,7 +485,8 @@ export function createGitDedup(options = {}) {
             return canonicalPath(resolve(cwd, expandHome(configured)));
         for (const legacy of ['~/.cache/gitx', '~/.gitx']) {
             const path = expandHome(legacy);
-            if (await isPresent(path))
+            const marker = await readFile(join(path, '.gitx-store'), 'utf8').catch(() => '');
+            if (marker === 'gitx-store-v2\n')
                 return canonicalPath(path);
         }
         return canonicalPath(expandHome('~/.git-dedup'));
@@ -409,17 +501,23 @@ export function createGitDedup(options = {}) {
         // containing unrelated histories. The graph is derived data, so omit it.
         await checked(['-C', pool, 'config', 'gc.writeCommitGraph', 'false']);
         await checked(['-C', pool, 'config', 'maintenance.commit-graph.enabled', 'false']);
+        // Consumers borrow objects that a force push can leave unreachable in the
+        // pool. Automatic gc would prune them, so only store prune deletes objects,
+        // after re-pinning every live consumer.
+        await checked(['-C', pool, 'config', 'gc.auto', '0']);
+        await checked(['-C', pool, 'config', 'maintenance.auto', 'false']);
+        await checked(['-C', pool, 'config', 'gc.pruneExpire', 'never']);
         await rm(join(pool, 'objects', 'info', 'commit-graph'), { force: true });
         await rm(join(pool, 'objects', 'info', 'commit-graphs'), { recursive: true, force: true });
         return pool;
     }
-    async function fetchRemote(root, remote, key) {
+    async function fetchRemote(root, remote, key, progress = false) {
         const pool = await ensurePool(root);
-        await fetchRemoteObjects(pool, remote, key);
+        await fetchRemoteObjects(pool, remote, key, progress);
         await registerRemote(root, remote, key);
         return pool;
     }
-    async function fetchRemoteObjects(pool, remote, key) {
+    async function fetchRemoteObjects(pool, remote, key, progress = false) {
         const id = remoteId(key);
         process.stderr.write(`git-dedup: updating object pool for ${key}\n`);
         await checked([
@@ -427,30 +525,40 @@ export function createGitDedup(options = {}) {
             pool,
             'fetch',
             '--no-tags',
+            ...(progress ? ['--progress'] : []),
             remote,
             `+refs/heads/*:refs/gitx/remotes/${id}/heads/*`,
             `+refs/tags/*:refs/gitx/remotes/${id}/tags/*`,
-        ]);
+        ], cwd, progress);
     }
     async function consumerTips(repo) {
         const refs = await checked(['for-each-ref', '--format=%(objectname)', 'refs'], repo);
         const head = await checked(['rev-parse', 'HEAD'], repo);
         return [...new Set([...refs.split('\n').filter(Boolean), head])].toSorted();
     }
-    async function pinnedTips(pool, id) {
-        return new Set((await checked(['-C', pool, 'for-each-ref', '--format=%(objectname)', `refs/gitx/consumers/${id}`]))
-            .split('\n')
-            .filter(Boolean));
+    async function unpinnedTips(pool, id, tips) {
+        // A tip that a remote ref holds needs no pin until the remote moves. Only
+        // store prune deletes objects, and it re-pins every live consumer first.
+        const held = new Set((await checked([
+            '-C',
+            pool,
+            'for-each-ref',
+            '--format=%(objectname)',
+            `refs/gitx/consumers/${id}`,
+            'refs/gitx/remotes',
+        ])).split('\n'));
+        return tips.filter((oid) => !held.has(oid));
     }
     async function pinConsumer(pool, repo, commonGitdir, tips) {
         // Immutable snapshots keep old tips reachable after force pushes, branch
-        // deletion, or a later cache call on the same checkout. Source ref names
+        // deletion, or a later store add call on the same checkout. Source ref names
         // cannot be copied into a files-backed pool: refs differing only by case
         // collide on case-insensitive filesystems. Object IDs are safe ref names,
         // and one pin per distinct tip preserves the same reachability.
         const id = await consumerId(commonGitdir);
-        const existing = await pinnedTips(pool, id);
-        const missing = tips.filter((oid) => !existing.has(oid));
+        // Register before pinning: prune refuses to run while pins lack a registration.
+        await registerConsumer(dirname(pool), id, commonGitdir);
+        const missing = await unpinnedTips(pool, id, tips);
         // Keep fetch argument lists bounded for repositories with many refs.
         for (let offset = 0; offset < missing.length; offset += 128)
             await checked([
@@ -479,37 +587,66 @@ export function createGitDedup(options = {}) {
     }
     async function clone(args, effectiveCwd) {
         const parsed = parseClone(args);
-        if (!parsed)
-            return undefined;
+        if (typeof parsed === 'string')
+            return fallback(args, parsed);
         const key = await remoteKey(parsed.remote, effectiveCwd);
         if (!key)
-            return undefined;
+            return fallback(args, 'remote is not a supported network URL');
         const destination = resolve(effectiveCwd, parsed.destination ?? defaultCloneName(parsed.remote));
-        if (await isPresent(destination))
-            return undefined;
+        // Like Git, clone into a missing or empty directory.
+        const entries = await readdir(destination).catch((error) => error.code === 'ENOENT' ? [] : undefined);
+        if (!entries || entries.length)
+            return fallback(args, `${destination} is not an empty directory`);
         const root = await storePath();
-        const cloned = await withLock(root, async () => {
-            const poolReused = options.onStorageReport ? await isPresent(poolPath(root)) : false;
-            let pool;
-            try {
-                pool = await fetchRemote(root, parsed.remote, key);
-            }
-            catch {
-                process.stderr.write('git-dedup: object pool unavailable; using Git clone\n');
-                return undefined;
-            }
-            const cloneArgs = ['clone', '--reference', pool, ...parsed.forwarded, parsed.remote, destination];
-            const result = await git(cloneArgs, effectiveCwd, true);
-            if (result.code !== 0)
-                return result.code;
-            await pinConsumer(pool, destination, await repoCommonGitdir(destination), await consumerTips(destination));
-            if (options.onStorageReport)
-                emitStorageReport({ operation: 'clone', repository: destination, poolReused, estimatedSavedBytes: 0 });
-            return 0;
+        // Lock only the pool writes. Only store prune deletes pool objects, so git clone can
+        // read the pool while other processes fetch or repack, and the new tips are pinned right after.
+        let poolReused = false;
+        let fetched;
+        let fetchError;
+        // Like git clone: progress on a terminal or with --progress, never with -q/--quiet.
+        const quiet = parsed.forwarded.some((arg) => arg === '-q' || arg === '--quiet');
+        const progress = !quiet && (process.stderr.isTTY || parsed.forwarded.includes('--progress'));
+        // Until the pin lands, this clone borrows pool objects that nothing pins, so
+        // store prune refuses while the marker exists. A failed pin leaves it behind.
+        const marker = join(root, 'clones', `${randomUUID()}.json`);
+        try {
+            fetched = await withLock(root, async () => {
+                poolReused = options.onStorageReport ? await isPresent(poolPath(root)) : false;
+                const pool = await fetchRemote(root, parsed.remote, key, progress).catch((error) => {
+                    fetchError = error;
+                    return undefined;
+                });
+                if (pool) {
+                    await mkdir(dirname(marker), { recursive: true });
+                    await writeFile(marker, JSON.stringify({ pid: process.pid, destination }) + '\n');
+                }
+                return pool;
+            });
+        }
+        catch {
+            return fallback(args, 'object pool lock unavailable');
+        }
+        if (!fetched)
+            return fallback(args, `object pool unavailable${gitFailure(fetchError)}`);
+        const pool = fetched;
+        const cloneArgs = ['clone', '--reference', pool, ...parsed.forwarded, parsed.remote, destination];
+        const result = await git(cloneArgs, effectiveCwd, true);
+        if (result.code !== 0) {
+            if (!(await isPresent(join(destination, '.git'))))
+                await rm(marker, { force: true });
+            return result.code;
+        }
+        const commonGitdir = await repoCommonGitdir(destination);
+        const tips = await consumerTips(destination);
+        await withLock(root, async () => {
+            await pinConsumer(pool, destination, commonGitdir, tips);
+            await rm(marker, { force: true });
         });
-        if (cloned === 0 && parsed.recurse)
+        if (options.onStorageReport)
+            emitStorageReport({ operation: 'clone', repository: destination, poolReused, estimatedSavedBytes: 0 });
+        if (parsed.recurse)
             return updateSubmodules(['update', '--init', '--recursive'], destination);
-        return cloned;
+        return 0;
     }
     async function seedSubmodules(repo) {
         const modulesFile = join(repo, '.gitmodules');
@@ -555,6 +692,21 @@ export function createGitDedup(options = {}) {
                 const pool = await fetchRemote(root, remote, key);
                 await mkdir(dirname(gitdir), { recursive: true });
                 await checked(['clone', '--bare', '--reference', pool, remote, gitdir]);
+                // Match a native submodule clone: remote-tracking refs, origin/HEAD, and only the default local branch.
+                await checked(['--git-dir', gitdir, 'config', 'remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*']);
+                await checked(['--git-dir', gitdir, 'fetch', '--quiet', 'origin']);
+                const head = await git(['--git-dir', gitdir, 'symbolic-ref', '--short', '-q', 'HEAD']);
+                const branch = head.code === 0 ? head.stdout.trim() : undefined;
+                if (branch) {
+                    await checked(['--git-dir', gitdir, 'remote', 'set-head', 'origin', branch]);
+                    await checked(['--git-dir', gitdir, 'config', `branch.${branch}.remote`, 'origin']);
+                    await checked(['--git-dir', gitdir, 'config', `branch.${branch}.merge`, `refs/heads/${branch}`]);
+                }
+                const others = (await checked(['--git-dir', gitdir, 'for-each-ref', '--format=%(refname:short)', 'refs/heads']))
+                    .split('\n')
+                    .filter((ref) => ref && ref !== branch);
+                if (others.length > 0)
+                    await checked(['--git-dir', gitdir, 'branch', '-D', ...others]);
                 await checked(['--git-dir', gitdir, 'config', 'core.bare', 'false']);
                 await checked(['--git-dir', gitdir, 'config', 'core.worktree', target]);
                 await pinConsumer(pool, gitdir, gitdir, await consumerTips(gitdir));
@@ -566,21 +718,30 @@ export function createGitDedup(options = {}) {
             const code = (await git(['submodule', ...args], at, true)).code;
             if (code !== 0)
                 return code;
-            const target = args.length === 2 ? defaultCloneName(args[1]) : args.length === 3 ? args[2] : undefined;
-            if (target && !target.startsWith('-')) {
+            const target = submoduleAddPath(args);
+            if (!target)
+                fallback(args, 'submodule path not recognized');
+            else {
                 try {
-                    await cache(resolve(at, target));
+                    await add(resolve(at, target));
                 }
                 catch (error) {
-                    process.stderr.write(`git-dedup: submodule cache unavailable (${String(error)})\n`);
+                    process.stderr.write(`git-dedup: submodule adoption unavailable (${String(error)})\n`);
                 }
             }
             return 0;
         }
-        if (args[0] !== 'update' || args.slice(1).some((arg) => !['--init', '--recursive', '--quiet', '-q'].includes(arg)))
+        if (args[0] !== 'update')
             return (await git(['submodule', ...args], at, true)).code;
-        if ((await git(['config', '--get', 'submodule.active'], at)).code === 0)
+        const unsupported = args.slice(1).find((arg) => !['--init', '--recursive', '--quiet', '-q'].includes(arg));
+        if (unsupported) {
+            fallback(args, `submodule update ${unsupported} is not supported`);
             return (await git(['submodule', ...args], at, true)).code;
+        }
+        if ((await git(['config', '--get', 'submodule.active'], at)).code === 0) {
+            fallback(args, 'submodule.active is configured');
+            return (await git(['submodule', ...args], at, true)).code;
+        }
         if (args.includes('--init')) {
             const init = (await git(['submodule', 'init'], at, true)).code;
             if (init !== 0)
@@ -589,8 +750,8 @@ export function createGitDedup(options = {}) {
         try {
             await seedSubmodules(at);
         }
-        catch {
-            process.stderr.write('git-dedup: submodule cache unavailable; using Git\n');
+        catch (error) {
+            fallback(args, `submodule adoption unavailable${gitFailure(error)}`);
         }
         const recursive = args.includes('--recursive') &&
             args.includes('--init') &&
@@ -616,8 +777,23 @@ export function createGitDedup(options = {}) {
         }
         return 0;
     }
-    async function cache(path = cwd) {
-        const result = { cached: 0, skipped: 0, failed: 0, repositories: [] };
+    /** Visit the checkout of every initialized submodule gitdir under a modules directory. */
+    async function visitModules(directory, visit) {
+        for (const entry of await readdir(directory, { withFileTypes: true }).catch(() => [])) {
+            if (!entry.isDirectory())
+                continue;
+            const modulePath = join(directory, entry.name);
+            if (await isPresent(join(modulePath, 'HEAD'))) {
+                const workTree = (await git(['--git-dir', modulePath, 'config', '--get', 'core.worktree'])).stdout.trim();
+                if (workTree)
+                    await visit(resolve(modulePath, workTree));
+            }
+            else
+                await visitModules(modulePath, visit);
+        }
+    }
+    async function add(path = cwd) {
+        const result = { added: 0, skipped: 0, failed: 0, repositories: [] };
         const visited = new Set();
         function record(repoPath, status, reason, detail) {
             result[status]++;
@@ -672,25 +848,27 @@ export function createGitDedup(options = {}) {
                         .split('\n')
                         .includes(join(pool, 'objects'));
                     const registered = (await readFile(join(root, 'remotes', `${remoteId(key)}.json`), 'utf8').catch(() => '')) ===
-                        JSON.stringify({ key, remote: url }) + '\n';
+                        registration(url, key);
                     const stateMatches = poolReused && alreadyLinked && registered && (await readFile(marker, 'utf8').catch(() => '')) === state;
-                    const currentPins = stateMatches ? await pinnedTips(pool, await consumerId(commonGitdir)) : undefined;
-                    if (currentPins && tips.every((oid) => currentPins.has(oid))) {
+                    const id = await consumerId(commonGitdir);
+                    if (stateMatches && !(await unpinnedTips(pool, id, tips)).length) {
+                        // Checkouts adopted before the consumer registry existed register here.
+                        await registerConsumer(root, id, commonGitdir);
                         record(repo, 'skipped', 'already current');
-                        process.stderr.write(`git-dedup: caching ${repo}: already current\n`);
+                        process.stderr.write(`git-dedup: adding ${repo}: already current\n`);
                         return;
                     }
-                    process.stderr.write(`git-dedup: caching ${repo}: packing local objects\n`);
+                    process.stderr.write(`git-dedup: adding ${repo}: packing local objects\n`);
                     // Gather loose local objects before adding an alternate; afterwards Git may
                     // consider a local object redundant and omit it from a new pack.
                     if (!alreadyLinked)
                         await checked(['-c', 'repack.writeBitmaps=false', 'repack', '-a', '-d', '-l'], repo);
                     const beforeUniqueBytes = await uniquePackBytes(commonGitdir);
-                    process.stderr.write(`git-dedup: caching ${repo}: importing refs\n`);
+                    process.stderr.write(`git-dedup: adding ${repo}: importing refs\n`);
                     stage = 'importing refs';
                     await pinConsumer(pool, repo, commonGitdir, tips);
                     stage = 'sharing objects';
-                    process.stderr.write(`git-dedup: caching ${repo}: sharing objects\n`);
+                    process.stderr.write(`git-dedup: adding ${repo}: sharing objects\n`);
                     await setAlternate(commonGitdir, pool);
                     await removeLegacyKeeps(commonGitdir);
                     await checked(['-c', 'repack.writeBitmaps=false', 'repack', '-a', '-d', '-l'], repo);
@@ -711,7 +889,7 @@ export function createGitDedup(options = {}) {
                     if (options.onStorageReport) {
                         const afterUniqueBytes = await uniquePackBytes(commonGitdir);
                         emitStorageReport({
-                            operation: 'cache',
+                            operation: 'add',
                             repository: repo,
                             poolReused,
                             beforeUniqueBytes,
@@ -719,33 +897,112 @@ export function createGitDedup(options = {}) {
                             estimatedSavedBytes: Math.max(0, beforeUniqueBytes - afterUniqueBytes),
                         });
                     }
-                    record(repo, 'cached', refreshError ? 'remote refresh deferred; retry with git-dedup store fetch' : undefined, refreshError ? String(refreshError) : undefined);
+                    record(repo, 'added', refreshError ? 'remote refresh deferred; retry with git-dedup store fetch' : undefined, refreshError ? String(refreshError) : undefined);
                     if (refreshError)
-                        process.stderr.write(`git-dedup: caching ${repo}: remote refresh deferred; retry with git-dedup store fetch\n`);
+                        process.stderr.write(`git-dedup: adding ${repo}: remote refresh deferred; retry with git-dedup store fetch\n`);
                 });
             }
             catch (error) {
-                record(repo, 'failed', cacheFailureReason(error, stage), String(error));
+                record(repo, 'failed', addFailureReason(error, stage), String(error));
             }
             finally {
-                await visitModules(join(gitdir, 'modules'));
+                await visitModules(join(gitdir, 'modules'), adopt);
             }
-            async function visitModules(directory) {
-                for (const entry of await readdir(directory, { withFileTypes: true }).catch(() => [])) {
-                    if (!entry.isDirectory())
-                        continue;
-                    const modulePath = join(directory, entry.name);
-                    if (await isPresent(join(modulePath, 'HEAD'))) {
-                        const workTree = (await git(['--git-dir', modulePath, 'config', '--get', 'core.worktree'])).stdout.trim();
-                        if (workTree)
-                            await adopt(resolve(modulePath, workTree));
-                    }
-                    else
-                        await visitModules(modulePath);
+        }
+        await adopt(resolve(cwd, path));
+        return result;
+    }
+    async function remove(path = cwd) {
+        const result = { removed: 0, skipped: 0, failed: 0, repositories: [] };
+        const visited = new Set();
+        const root = await storePath();
+        const pool = poolPath(root);
+        const poolObjects = join(pool, 'objects');
+        function record(entry) {
+            result[entry.status]++;
+            result.repositories.push(entry);
+        }
+        async function detach(repo) {
+            let commonGitdir;
+            try {
+                commonGitdir = await repoCommonGitdir(repo);
+            }
+            catch (error) {
+                const missing = !(await isPresent(repo));
+                record({
+                    path: repo,
+                    status: missing ? 'failed' : 'skipped',
+                    reason: missing
+                        ? `path not found; if this checkout was deleted, run git-dedup store remove --forget ${repo}`
+                        : 'not a Git repository or path is unavailable',
+                    detail: String(error),
+                });
+                return;
+            }
+            // Linked worktrees share one object database, so detach it once.
+            if (visited.has(commonGitdir))
+                return;
+            visited.add(commonGitdir);
+            const gitdirs = [
+                commonGitdir,
+                ...(await readdir(join(commonGitdir, 'worktrees')).catch(() => [])).map((name) => join(commonGitdir, 'worktrees', name)),
+            ];
+            const alternate = join(commonGitdir, 'objects', 'info', 'alternates');
+            try {
+                const original = await readFile(alternate, 'utf8').catch(() => '');
+                const lines = original.split('\n');
+                if (!lines.includes(poolObjects)) {
+                    record({ path: repo, status: 'skipped', reason: 'not linked to the store' });
+                    return;
                 }
+                if (!(await isPresent(pool)))
+                    throw new Error(`Object pool is missing: ${pool}`);
+                // Lock without initializing: removal must never create a store.
+                await lockDirectory(storeLock(root), async () => {
+                    process.stderr.write(`git-dedup: removing ${repo}: copying shared objects\n`);
+                    // Without -l, repack copies every object reachable from refs, reflogs, and
+                    // the indexes of all worktrees, including objects read through the pool.
+                    await checked(['-c', 'repack.writeBitmaps=false', 'repack', '-a', '-d', '--pack-kept-objects'], repo);
+                    const remaining = lines.filter((line) => line && line !== poolObjects);
+                    if (remaining.length)
+                        await writeFile(alternate, remaining.join('\n') + '\n');
+                    else
+                        await rm(alternate);
+                    try {
+                        await checked(['fsck', '--connectivity-only'], repo);
+                    }
+                    catch (error) {
+                        await writeFile(alternate, original);
+                        throw error;
+                    }
+                    const id = (await readFile(join(commonGitdir, 'gitx-consumer-id'), 'utf8').catch(() => '')).trim();
+                    if (/^[a-f0-9-]{36}$/.test(id)) {
+                        const pins = await checked([
+                            '-C',
+                            pool,
+                            'for-each-ref',
+                            '--format=delete %(refname)',
+                            `refs/gitx/consumers/${id}`,
+                        ]);
+                        if (pins)
+                            await checked(['-C', pool, 'update-ref', '--stdin'], cwd, false, pins + '\n');
+                        await rm(join(root, 'consumers', `${id}.json`), { force: true });
+                    }
+                    await rm(join(commonGitdir, 'gitx-consumer-id'), { force: true });
+                    for (const gitdir of gitdirs)
+                        await rm(join(gitdir, 'gitx-cache.json'), { force: true });
+                });
+                record({ path: repo, status: 'removed', objectBytes: await directorySize(join(commonGitdir, 'objects')) });
+            }
+            catch (error) {
+                record({ path: repo, status: 'failed', reason: 'could not detach from the store', detail: String(error) });
+            }
+            finally {
+                for (const gitdir of gitdirs)
+                    await visitModules(join(gitdir, 'modules'), detach);
             }
         }
-        await adopt(resolve(cwd, path));
+        await detach(resolve(cwd, path));
         return result;
     }
     async function storeInfo() {
@@ -776,25 +1033,33 @@ export function createGitDedup(options = {}) {
                 typeof value.remote !== 'string' ||
                 `${remoteId(value.key)}.json` !== name)
                 throw new Error(`Invalid git-dedup remote registration: ${name}`);
-            return { key: value.key, remote: value.remote };
+            return { key: value.key, remote: redactRemote(value.remote, '***') };
         }));
         return remotes.toSorted((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
     }
     async function fetch() {
         const root = await storePath();
-        let fetched = 0;
+        const remotes = [];
         await withLock(root, async () => {
             for (const name of await readdir(join(root, 'remotes')).catch(() => [])) {
                 if (!name.endsWith('.json'))
                     continue;
                 const { key, remote } = JSON.parse(await readFile(join(root, 'remotes', name), 'utf8'));
-                await fetchRemote(root, remote, key);
-                fetched++;
+                try {
+                    await fetchRemote(root, remote, key);
+                    remotes.push({ key, status: 'fetched' });
+                }
+                catch (error) {
+                    const detail = String(error);
+                    const reason = /fatal: (.+)/.exec(detail)?.[1] ?? 'remote fetch failed';
+                    remotes.push({ key, status: 'failed', reason, detail });
+                }
             }
-            if (fetched)
+            if (remotes.some((result) => result.status === 'fetched'))
                 await checked(['-C', poolPath(root), 'repack', '-d', '--geometric=2']);
         });
-        return { fetched };
+        const fetched = remotes.filter((result) => result.status === 'fetched').length;
+        return { fetched, failed: remotes.length - fetched, remotes };
     }
     async function gc() {
         const root = await storePath();
@@ -805,20 +1070,171 @@ export function createGitDedup(options = {}) {
         });
         return { compacted: true };
     }
-    async function doctor() {
+    /** Every object a consumer may borrow from the pool without a pin. */
+    async function liveTips(commonGitdir) {
+        if ((await git(['--git-dir', commonGitdir, 'config', '--get', 'extensions.refStorage'], commonGitdir)).stdout.trim())
+            throw new Error(`Refusing to prune: ${commonGitdir} uses a ref storage format that git-dedup cannot inspect`);
+        const tips = new Set();
+        const extra = new Set();
+        const worktrees = (await readdir(join(commonGitdir, 'worktrees')).catch(() => [])).map((name) => join(commonGitdir, 'worktrees', name));
+        for (const gitdir of [commonGitdir, ...worktrees]) {
+            // Per-worktree refs and HEAD, then the index: git add skips blobs the pool already has.
+            for (const oid of (await checked(['--git-dir', gitdir, 'for-each-ref', '--format=%(objectname)'], gitdir)).split('\n'))
+                if (oid)
+                    tips.add(oid);
+            const head = await git(['--git-dir', gitdir, 'rev-parse', '--verify', '-q', 'HEAD'], gitdir);
+            if (head.code === 0)
+                tips.add(head.stdout.trim());
+            if (await isPresent(join(gitdir, 'index'))) {
+                const tree = await git(['--git-dir', gitdir, 'write-tree'], gitdir);
+                if (tree.code !== 0)
+                    throw new Error(`Refusing to prune: cannot record the index of ${gitdir}: ${tree.stderr.trim()}`);
+                // Git always has the empty tree, so it needs no pin.
+                if (tree.stdout.trim() !== '4b825dc642cb6eb9a060e54bf8d69288fbee4904')
+                    tips.add(tree.stdout.trim());
+            }
+            // Pseudorefs and in-progress rebase or cherry-pick state can name fetched commits no ref holds.
+            const files = ['FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'REBASE_HEAD'].map((name) => join(gitdir, name));
+            for (const directory of ['rebase-merge', 'rebase-apply', 'sequencer'])
+                for (const entry of await readdir(join(gitdir, directory), { withFileTypes: true }).catch(() => []))
+                    if (entry.isFile())
+                        files.push(join(gitdir, directory, entry.name));
+            for (const file of files)
+                for (const oid of (await readFile(file, 'utf8').catch(() => '')).match(/\b[0-9a-f]{40}\b/g) ?? [])
+                    if (!tips.has(oid))
+                        extra.add(oid);
+        }
+        // Commits held only by reflogs or state files; pin the tips of each abandoned history.
+        const abandoned = await checked(['--git-dir', commonGitdir, 'rev-list', '--parents', '--ignore-missing', '--reflog', ...extra, '--not', '--all'], commonGitdir);
+        const commits = new Set();
+        const parents = new Set();
+        for (const line of abandoned.split('\n').filter(Boolean)) {
+            const [commit, ...rest] = line.split(' ');
+            commits.add(commit);
+            for (const parent of rest)
+                parents.add(parent);
+        }
+        for (const commit of commits)
+            if (!parents.has(commit))
+                tips.add(commit);
+        return [...tips].toSorted();
+    }
+    async function prune() {
         const root = await storePath();
+        const pool = poolPath(root);
+        if (!(await isPresent(pool)))
+            return { reclaimedBytes: 0 };
         return withLock(root, async () => {
-            const checks = [];
-            const pool = await ensurePool(root);
-            checks.push({
-                name: 'pool',
-                ok: true,
-                detail: `${pool}: SHA-1 object database`,
-            });
+            const registry = await registeredConsumers(root);
+            // A clone between its pool fetch and its pin borrows objects that nothing pins yet.
+            for (const name of await readdir(join(root, 'clones')).catch(() => [])) {
+                const { pid, destination } = JSON.parse(await readFile(join(root, 'clones', name), 'utf8'));
+                if (processExists(pid))
+                    throw new Error(`Refusing to prune: a clone into ${destination} is in progress; retry when it finishes.`);
+                const id = (await readFile(join(destination, '.git', 'gitx-consumer-id'), 'utf8').catch(() => '')).trim();
+                if ((await isPresent(join(destination, '.git'))) && !registry.has(id))
+                    throw new Error(`Refusing to prune: the clone into ${destination} was never registered. ` +
+                        `Run git-dedup store add ${destination}, or delete that checkout, then retry.`);
+                await rm(join(root, 'clones', name));
+            }
+            const pinned = new Set((await checked(['-C', pool, 'for-each-ref', '--format=%(refname)', 'refs/gitx/consumers']))
+                .split('\n')
+                .filter(Boolean)
+                .map((ref) => ref.split('/')[3]));
+            const unregistered = [...pinned].filter((id) => !registry.has(id));
+            if (unregistered.length)
+                throw new Error(`Refusing to prune: the pool holds objects for ${unregistered.length} unregistered checkout(s). ` +
+                    'Run git-dedup store add for every checkout that uses this store (for example ' +
+                    'git-dedup store add --all <directory>), then retry.');
+            // A moved checkout still borrows through its absolute alternate path, including
+            // objects fetched after its last pin. Only the user can say it was deleted.
+            const missing = [];
+            for (const [id, gitdir] of registry)
+                if (!(await carriesConsumerId(gitdir, id)))
+                    missing.push(gitdir);
+            if (missing.length)
+                throw new Error(`Refusing to prune: ${missing.length} registered checkout(s) cannot be found:\n` +
+                    missing.map((gitdir) => `  ${checkoutPath(gitdir)}\n`).join('') +
+                    'If this checkout was moved, run git-dedup store add <new path>. ' +
+                    'If it was deleted, run git-dedup store remove --forget <old path>.');
+            for (const gitdir of registry.values())
+                await pinConsumer(pool, gitdir, gitdir, await liveTips(gitdir));
+            const before = await directorySize(pool);
+            // Explicit expiry: the pool never prunes automatically.
+            await checked(['-C', pool, 'gc', '--prune=now']);
+            return { reclaimedBytes: Math.max(0, before - (await directorySize(pool))) };
+        });
+    }
+    /** Release a registered checkout that no longer exists. Returns the Git directories forgotten. */
+    async function forget(path) {
+        const root = await storePath();
+        const target = resolve(cwd, path);
+        const candidates = new Set();
+        for (const base of [target, await canonicalPath(target)])
+            candidates.add(base).add(join(base, '.git'));
+        if (!(await isPresent(root)))
+            return [];
+        return lockDirectory(storeLock(root), async () => {
+            const forgotten = [];
+            let present = false;
+            for (const [id, gitdir] of await registeredConsumers(root)) {
+                if (!candidates.has(gitdir))
+                    continue;
+                // A new checkout at a deleted checkout's path is live; forget only the old registration.
+                if (await carriesConsumerId(gitdir, id)) {
+                    present = true;
+                    continue;
+                }
+                if (await isPresent(poolPath(root))) {
+                    const pins = await checked([
+                        '-C',
+                        poolPath(root),
+                        'for-each-ref',
+                        '--format=delete %(refname)',
+                        `refs/gitx/consumers/${id}`,
+                    ]);
+                    if (pins)
+                        await checked(['-C', poolPath(root), 'update-ref', '--stdin'], cwd, false, pins + '\n');
+                }
+                await rm(join(root, 'consumers', `${id}.json`));
+                forgotten.push(gitdir);
+            }
+            if (!forgotten.length && present)
+                throw new Error(`${path} still exists; run git-dedup store remove without --forget to detach it`);
+            return forgotten;
+        });
+    }
+    async function doctor() {
+        const root = await storePath();
+        const checks = [];
+        const pool = poolPath(root);
+        const empty = !(await isPresent(pool));
+        if (!empty) {
+            try {
+                const format = await checked(['-C', pool, 'rev-parse', '--show-object-format']);
+                const bare = await checked(['-C', pool, 'rev-parse', '--is-bare-repository']);
+                checks.push({
+                    name: 'pool',
+                    ok: format === 'sha1' && bare === 'true',
+                    detail: `${pool}: ${format === 'sha1' ? 'SHA-1' : format.toUpperCase()} ${bare === 'true' ? 'bare' : 'non-bare'} object database`,
+                });
+            }
+            catch (error) {
+                checks.push({
+                    name: 'pool',
+                    ok: false,
+                    detail: `${pool}: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
+        try {
             const binary = await gitPath();
             checks.push({ name: 'git', ok: true, detail: `${binary}: ${await checked(['--version'])}` });
-            return { checks };
-        });
+        }
+        catch (error) {
+            checks.push({ name: 'git', ok: false, detail: error instanceof Error ? error.message : String(error) });
+        }
+        return { empty, checks };
     }
     async function addWorktree(args, at) {
         if (args[0] !== 'add')
@@ -855,8 +1271,10 @@ export function createGitDedup(options = {}) {
             ].includes(arg) ||
                 /^(--reason|--track)=/.test(arg))
                 continue;
-            if (arg.startsWith('-'))
+            if (arg.startsWith('-')) {
+                fallback(args, `worktree add ${arg.split('=')[0]} is not supported`);
                 return (await git(['worktree', ...args], at, true)).code;
+            }
             path = arg;
             break;
         }
@@ -872,8 +1290,16 @@ export function createGitDedup(options = {}) {
     }
     async function run(args) {
         const parsed = parseGlobal(args, cwd);
-        if (incomingEnv.GITX_ACTIVE === '1' || incomingEnv.GIT_DEDUP_ACTIVE === '1' || hasRepositoryEnvironment || !parsed)
+        if (incomingEnv.GITX_ACTIVE === '1' || incomingEnv.GIT_DEDUP_ACTIVE === '1' || !parsed)
             return (await git(args, cwd, true)).code;
+        const managed = parsed.command === 'clone' ||
+            (parsed.command === 'submodule' && ['add', 'update'].includes(parsed.rest[0])) ||
+            (parsed.command === 'worktree' && parsed.rest[0] === 'add');
+        if (hasRepositoryEnvironment) {
+            if (managed)
+                fallback(parsed.rest, 'Git repository environment variables are set');
+            return (await git(args, cwd, true)).code;
+        }
         // -C is resolved explicitly. Other global options can change Git semantics, so forward intact.
         for (let i = 0; i < parsed.prefix.length; i++) {
             const arg = parsed.prefix[i];
@@ -883,6 +1309,8 @@ export function createGitDedup(options = {}) {
             }
             if (arg.startsWith('-C'))
                 continue;
+            if (managed)
+                fallback(parsed.rest, `global option ${arg.split('=')[0]} is not supported`);
             return (await git(args, cwd, true)).code;
         }
         if (parsed.cwd !== cwd) {
@@ -906,7 +1334,7 @@ export function createGitDedup(options = {}) {
             throw new Error(`git --version failed: ${result.stderr.trim()}`);
         return result.stdout.trim();
     }
-    return { run, cache, storeInfo, listRemotes, fetch, gc, doctor, storePath, gitVersion };
+    return { run, add, remove, storeInfo, listRemotes, fetch, gc, prune, forget, doctor, storePath, gitVersion, gitPath };
 }
 function processExists(pid) {
     try {