abhigyanpatwari/GitNexus · error · GitNexusRcError

${source}: branch name must not start with "-".

Error message

${source}: branch name must not start with "-".

What it means

Thrown by validateBranchName() when the branch name starts with '-'. A leading dash makes the value look like a CLI flag, which would break argument parsing wherever the branch is later interpolated into a command or argument list.

Source

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

  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).`,
    );
  }
  return trimmed;
}

View on GitHub (pinned to d540b00184)

Solutions

1. Prefix the name with a letter or digit (e.g. 'feature/...' or 'T123-...').
2. If the leading dash was accidental, remove it.
3. Use git's conventional 'feature/', 'bugfix/', or 'release/' prefixes.

Example fix

# before
gitnexus analyze --default-branch "-my-branch"

# after
gitnexus analyze --default-branch "my-branch"

function assertNoLeadingDash(name: string): void {
  if (name.startsWith('-')) {
    throw new Error('branch name must not start with "-"');
  }
}

function hasNoLeadingDash(name: string): boolean {
  return typeof name === 'string' && !name.startsWith('-');
}

When it happens

Trigger: Passing --default-branch '-feature' or a name beginning with a dash from a config typo.

Common situations: A branch name autogenerated as '-' + ticket-id where the ticket id was empty; a copy-paste that included a leading dash from a markdown list item.

Related errors

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

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