abhigyanpatwari/GitNexus · warning · GitNexusRcError

: branch name must not contain "..".

Error message

${source}: branch name must not contain "..".

What it means

On Windows with a non-ASCII path, both the 8.3 short-name conversion and the main-thread junction fallback failed to produce an ASCII-safe form, so the original path is passed through and LadybugDB may fail with "Cannot open file." This is the terminal degradation of toNativeSafePath — every mitigation was attempted.

Solutions

1. Move the repo to a path without CJK/Unicode characters — the message's primary recommendation
2. Or enable 8.3 short names: fsutil 8dot3name set 0 (admin), then place/copy files anew so short names are generated
3. Verify short names now resolve: fsutil file queryshortname <file>
4. If LadybugDB still errors 'Cannot open file.' after this warn, the path is being used verbatim — relocation is the reliable fix

Example fix

:: before
C:\Users\太田\repos\my-repo> npx gitnexus analyze

:: after
C:\src\my-repo> npx gitnexus analyze
:: or, on the original volume (admin):
fsutil 8dot3name set 0

import fs from 'node:fs';
import { execSync } from 'node:child_process';
const NON_ASCII_RE = /[^\x00-\x7f]/;
// fail fast with an actionable message before analysis starts
export const assertAsciiSafePath = (p: string): void => {
  if (process.platform !== 'win32' || !NON_ASCII_RE.test(p)) return;
  let shortNamesEnabled = false;
  try {
    shortNamesEnabled = /8dot3name creation is enabled/i
      .test(execSync(`fsutil 8dot3name query ${p.slice(0, 2)}`).toString());
  } catch {}
  if (!shortNamesEnabled) {
    throw new Error(
      `Non-ASCII path "${p}" with 8.3 names disabled: move the repo to an ASCII path ` +
      'or run `fsutil 8dot3name set 0`.',
    );
  }
};

const needsAsciiSafePath = (p: string): boolean =>
  process.platform === 'win32' && /[^\x00-\x7f]/.test(p);

When it happens

Trigger: tryShortPath(p) returns null AND tryJunction(targetDir, leaf) fails or the target dir does not exist, on the main thread with a NON_ASCII_RE-matching path — 8.3 generation disabled and junction creation blocked (permissions, volume type, path length).

Common situations: CJK/emoji/extended-Unicode repo paths on volumes with 8.3 naming stripped; locked-down machines where creating junctions is denied; storage roots on network shares that do not support junctions or short names.

Related errors

• Failed to remove the LadybugDB index files — still present…
• GitNexus could not move the LadybugDB WAL sidecar at
• GitNexus: failed to reclaim missing-shadow WAL quarantines
• GitNexus: failed to release init lock
• : branch name must not contain whitespace.

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-08-20). Data as JSON: /api/errors/dad862f881c8f69f. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/cli/analyze-config.ts:185

  }
  if (trimmed.length > BRANCH_MAX_LENGTH) {
    throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
  }
  assertNoHiddenChars(trimmed, source);
  if (/\s/.test(trimmed)) {
    throw new GitNexusRcError(`${source}: branch name must not contain whitespace.`);
  }
  // git ref-name rules (subset): reject characters git itself forbids in refs.
  if (/[~^:?*[\\]/.test(trimmed)) {
    throw new GitNexusRcError(
      `${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`,
    );
  }
  if (trimmed.startsWith('-')) {
    throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
  }
  if (trimmed.includes('..')) {
    throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
  }
  // Git permits a backtick in a ref, but the branch is embedded inside a
  // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
  // example, where a backtick would close the span early and let the rest of
  // the template render as instruction text. Reject it at this single
  // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
  // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
  if (trimmed.includes('`')) {
    throw new GitNexusRcError(
      `${source}: branch name must not contain a backtick (it would break the generated Markdown).`,
    );
  }
  return trimmed;
}

/**
 * Best-effort validation for an auto-detected branch (from git). Never throws —
 * returns `undefined` for anything unusable so the resolver falls back to the

View on GitHub (pinned to 52924ef12c)