abhigyanpatwari/GitNexus · error · GitNexusRcError

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

Error message

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

What it means

Thrown by validateBranchName() when the (already trimmed) branch name contains any whitespace character (spaces, tabs, newlines). Git refnames cannot contain whitespace, and the branch is interpolated into a shell-like context in generated docs, so whitespace would break the example command.

Source

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

  }
};

/**
 * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
 * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
 * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
 */
export function validateBranchName(value: string, source: string): string {
  const trimmed = value.trim();
  if (!trimmed) {
    throw new GitNexusRcError(`${source}: branch name must not be empty.`);
  }
  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

View on GitHub (pinned to d540b00184)

Solutions

1. Replace internal whitespace with hyphens or underscores.
2. Re-type the branch name without spaces.
3. Verify the branch exists locally with `git branch --list` and copy the exact token.

Example fix

# before
gitnexus analyze --default-branch "feature/auth refactor"

# after
gitnexus analyze --default-branch "feature/auth-refactor"

function assertNoWhitespaceInBranch(name: string): void {
  if (/\s/.test(name.trim())) {
    throw new Error('branch name must not contain whitespace');
  }
}

function isBranchWithoutWhitespace(name: string): boolean {
  return typeof name === 'string' && !/\s/.test(name.trim());
}

When it happens

Trigger: Passing --default-branch 'feature foo' (internal space), a name with a trailing tab that survived trim of outer spaces, or a multi-line value.

Common situations: A branch name with a typo'd space ('feature/ auth' instead of 'feature/auth'); pasting a name that included a newline; a config editor that auto-wrapped a long line.

Related errors

• ${source}: branch name must not be empty.
• ${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}
• ${source}: branch name contains characters not allowed in a
• ${source}: branch name must not start with "-".
• ${source}: branch name must not contain "..".

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/3408d725bd0c0fff. Report an issue: GitHub.