What causes "${command} failed: ${detail}" in Egonex-AI/Understand-Anything?

Read the detail in the error message (it is git's stderr) and fix the underlying git problem it names — e.g. `git fetch ` if the base commit is missing.

Egonex-AI/Understand-Anything · error

${command} failed: ${detail}

Error message

${command} failed: ${detail}

What it means

run() in prepare-incremental.mjs executes an external command (primarily git) synchronously via spawnSync. If the process exits with a non-zero status, the error is wrapped as `<command> failed: <stderr-or-stdout-or-exit-code>`, surfacing the child's diagnostic output. It is thrown for any subcommand failure — e.g. git rev-parse on a nonexistent ref, or git diff against an unknown commit.

Source

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

    'incremental-symbol-report.json',
    'incremental-edge-candidates.json',
  ]);
  for (const name of readdirSync(intermediateDir)) {
    if (exactNames.has(name) || /^batch-\d+(?:-part-\d+)?\.json$/.test(name)) {
      unlinkSync(join(intermediateDir, name));
    }
  }
}

function run(command, args, options = {}) {
  const result = spawnSync(command, args, {
    cwd: options.cwd,
    encoding: 'utf-8',
    maxBuffer: 256 * 1024 * 1024,
  });
  if (result.status !== 0) {
    const detail = result.stderr?.trim() || result.stdout?.trim() || `exit ${result.status}`;
    throw new Error(`${command} failed: ${detail}`);
  }
  if (result.stderr) process.stderr.write(result.stderr);
  return result.stdout;
}

function resolveCommit(projectRoot, value) {
  return run(
    'git',
    ['rev-parse', '--verify', '--end-of-options', `${value}^{commit}`],
    { cwd: projectRoot },
  ).trim();
}

function parseNameStatusZ(output) {
  if (!output) return [];
  const fields = output.split('\0');
  if (fields.at(-1) === '') fields.pop();
  const changes = [];

View on GitHub (pinned to 07edf82a04)

Solutions

Read the detail in the error message (it is git's stderr) and fix the underlying git problem it names — e.g. `git fetch <remote> <sha>` if the base commit is missing.
Verify the base/head commits exist: `git rev-parse --verify <value>^{commit}` in the project root; use a branch or SHA that is present locally.
For CI shallow clones, unshallow or deepen history before the incremental run (`git fetch --unshallow` or `git fetch --deepen=...`) so the base commit is available.
If git reports 'detected dubious ownership', run `git config --global --add safe.directory <projectRoot>`; ensure the project root is an actual git work tree.

Example fix

// before: preparing an incremental update against a base commit missing from a shallow clone
node prepare-incremental.mjs . --base 9a1b2c3   // git rev-parse fails

// after: fetch the missing history first
git fetch --unshallow   # or: git fetch origin 9a1b2c3
node prepare-incremental.mjs . --base 9a1b2c3

Defensive patterns

Strategy: retry

Validate before calling

// verify commits exist before running the incremental flow
import { execFileSync } from 'node:child_process';
function commitExists(root, value) {
  try { execFileSync('git', ['rev-parse', '--verify', `${value}^{commit}`], { cwd: root }); return true; }
  catch { return false; }
}

Try / catch

try {
  await prepareIncremental(projectRoot, { base: baseCommit });
} catch (err) {
  if (/^git failed:/.test(err.message) && /bad revision|unknown revision/.test(err.message)) {
    execFileSync('git', ['fetch', 'origin', baseCommit], { cwd: projectRoot });
    return prepareIncremental(projectRoot, { base: baseCommit });
  }
  throw err;
}

Prevention

Fetch enough history for the base commit (avoid depth=1 shallow checkouts for incremental runs, or use git fetch --unshallow).
Always pass commits that exist locally: verify with `git rev-parse --verify <sha>^{commit}` first.
Run the tool from inside the git work tree, and resolve safe.directory ownership errors before starting.
Log the command and its stderr (the error detail already contains it) to distinguish missing-commit failures from repo corruption.

When it happens

Trigger: Calling prepare-incremental.mjs (or anything using run()) where a spawned command exits non-zero: resolveCommit on a base/head commit that does not exist in the repo, git diff against a value that is not a valid commit, a detached/shallow clone missing history, or git not behaving as expected (e.g. corrupt index, ownership 'dubious repository' errors).

Common situations: The base commit was garbage-collected or belongs to a remote branch not fetched locally; shallow clones (CI checkouts with depth=1) lack the base commit; the user passes a wrong commit SHA/branch name to the incremental flow; running in a directory that is not a git work tree; git's safe.directory ownership check rejects the repo.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

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