abhigyanpatwari/GitNexus · error · GitNexusRcError

${source}: branch name contains characters not allowed in a

Error message

${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).

What it means

Thrown by validateBranchName() when the branch name contains any character git forbids in a refname: ~ ^ : ? * [ \. These characters have special meaning to git (revision syntax, globbing, path separators) and would break the generated checkout command or be rejected by git itself.

Source

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

 * 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
  // 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).`,

View on GitHub (pinned to d540b00184)

Solutions

Use only git-refname-safe characters: letters, digits, '-', '_', '.', '/'.
Replace any ':' or '\' with '-' or '/'.
If you meant to pass a revision expression, that is not supported here — pass a branch name.

Example fix

// before
{ "defaultBranch": "bugfix:auth" }

// after
{ "defaultBranch": "bugfix/auth" }

Defensive patterns

Strategy: validation

Validate before calling

function assertGitRefSafe(name: string): void {
  if (/[~^:?*[\\]/.test(name)) {
    throw new Error(`branch name contains a forbidden git-ref character`);
  }
}

Type guard

function isGitRefSafe(name: string): boolean {
  return typeof name === 'string' && !/[~^:?*[\\]/.test(name);
}

Prevention

Restrict branch names to [A-Za-z0-9._-/] plus the allowed prefix shapes.
Never pass a git rev-parse expression (HEAD~1, A:B) where a branch name is expected.
On Windows, watch for backslashes leaked from path copy-paste.

When it happens

Trigger: Passing a branch name containing '~' (as in 'HEAD~1'), ':' (revision range syntax), '*' (glob), '?' (single-match), '[' (charclass), '^' (parent), or '\' (Windows path separator leaked in).

Common situations: A Windows user pasting a branch name that included a backslash; a name like 'fix:wip' using a colon; an attempt to pass a git rev-parse expression instead of a branch.

Related errors

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