Working tree has relevant uncommitted changes: ${preview}${s

Error message

Working tree has relevant uncommitted changes: ${preview}${suffix}. Commit or stash them before incremental analysis so the HEAD baseline remains reproducible.

What it means

main checks for uncommitted changes in the working tree that are relevant to the analysis (after exclude filtering). If any exist, incremental analysis is refused because the HEAD baseline would be irreproducible — the diff against baseCommit would not reflect a clean, committed state, so symbol protection could be computed against the wrong content.

Source

Thrown at understand-anything-plugin/skills/understand/prepare-incremental.mjs:489

    );
  }
  return { projectRoot: positionals[0], baseCommit: positionals[1], excludePatterns };
}

async function main() {
  const args = parseArgs(process.argv.slice(2));
  const projectRoot = realpathSync(args.projectRoot);
  const uaDir = resolveUaDir(projectRoot);
  const intermediateDir = join(uaDir, 'intermediate');
  mkdirSync(intermediateDir, { recursive: true });

  const baseCommit = resolveCommit(projectRoot, args.baseCommit);
  const headCommit = resolveCommit(projectRoot, 'HEAD');
  const dirtyPaths = relevantWorktreeChanges(projectRoot, args.excludePatterns);
  if (dirtyPaths.length > 0) {
    const preview = dirtyPaths.slice(0, 10).join(', ');
    const suffix = dirtyPaths.length > 10 ? ` (+${dirtyPaths.length - 10} more)` : '';
    throw new Error(
      `Working tree has relevant uncommitted changes: ${preview}${suffix}. ` +
      `Commit or stash them before incremental analysis so the HEAD baseline remains reproducible.`,
    );
  }
  const changes = parseNameStatusZ(
    run(
      'git',
      ['diff', '--name-status', '-z', '--relative', baseCommit, headCommit, '--', '.'],
      { cwd: projectRoot },
    ),
  );
  const diffPaths = pathsFromChanges(changes);

  const scanPath = join(intermediateDir, 'scan-result.json');
  const oldScan = readJson(scanPath, {});
  const graph = readJson(join(uaDir, 'knowledge-graph.json'), {});
  const oldFingerprints = normalizeFingerprintStore(
    readJson(join(uaDir, 'fingerprints.json'), null),

View on GitHub (pinned to 07edf82a04)

Solutions

Commit the changes: git add -A && git commit -m "..." then re-run
Stash them: git stash (or git stash -u for untracked) and re-run
Exclude irrelevant dirty files: --exclude <patterns> if they are generated/local-only files
Add generated paths to .gitignore or the script's exclude patterns so they never count as relevant

Example fix

// before
node prepare-incremental.mjs . HEAD~1   # fails with dirty worktree
// after
git stash -u
node prepare-incremental.mjs . HEAD~1
git stash pop

Defensive patterns

Strategy: validation

Validate before calling

const dirty = execSync('git status --porcelain', { cwd: projectRoot }).toString().trim();
if (dirty) throw new Error('Commit or stash uncommitted changes before incremental analysis');

Try / catch

try {
  await prepareIncremental(args);
} catch (err) {
  if (String(err.message).startsWith('Working tree has relevant uncommitted changes')) {
    console.error(err.message);
    // either instruct user to commit/stash, or auto-stash:
    execSync('git stash -u');
    return prepareIncremental(args).finally(() => execSync('git stash pop'));
  }
  throw err;
}

Prevention

Run git status --porcelain and ensure it is empty before incremental prep
Exclude generated/local-only paths via --exclude or .gitignore so they do not count as relevant
In CI, always work from a clean checkout

When it happens

Trigger: relevantWorktreeChanges returns one or more paths (limited preview of 10 in the message) because the repo has modified, staged, added, or deleted files matching analysis scope at the time prepare-incremental.mjs runs.

Common situations: Running incremental preparation mid-development with unsaved/uncommitted edits, CI checking out a branch with local modifications, or generated files appearing in the worktree that are not excluded and not gitignored.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/b3c27707c06f5364. Report an issue: GitHub.