pcottle/learnGitBranching · error · GitError

bad-branch-name

Error message

bad-branch-name

What it means

Branch names must match /^(\w([./-]?\w+)*)$/ and must not start with 'o/' (reserved for remote-tracking refs). Any other name — spaces, leading dash/slash, trailing punctuation, etc. — throws bad-branch-name.

Source

Thrown at src/js/git/index.js:700

GitEngine.prototype.getDetachedHead = function() {
  // detached head is if HEAD points to a commit instead of a branch...
  var target = this.HEAD.get('target');
  var targetType = target.get('type');
  return targetType !== 'branch';
};

GitEngine.prototype.validateBranchName = function(name) {
  // Lets escape some of the nasty characters
  name = name.replace(///g,"\/");
  name = name.replace(/\s/g, '');
  // And then just make sure it starts with alpha-numeric,
  // can contain a slash or dash, and then ends with alpha
  if (
    !/^\w([.\/\-]?\w+)*$/.test(name) ||
    name.search('o/') === 0
  ) {
    throw new GitError({
      msg: intl.str(
        'bad-branch-name',
        { branch: name }
      )
    });
  }
  if (/^[cC]\d+$/.test(name)) {
    throw new GitError({
      msg: intl.str(
        'bad-branch-name',
        { branch: name }
      )
    });
  }
  if (/[hH][eE][aA][dD]/.test(name)) {
    throw new GitError({
      msg: intl.str(
        'bad-branch-name',

View on GitHub (pinned to 5b09d0ff96)

Solutions

1. Use letters/digits separated by single . / - separators, e.g. feature-x or bug/fix1
2. Wrap names in quotes in the command line to preserve them
3. Never prefix local branches with o/

Example fix

// before
git branch my feature
// after
git branch my-feature

function isValidBranchName(n){ return /^\w([.\/-]?\w+)*$/.test(n) && n.indexOf('o/') !== 0; }

function isValidBranchName(n){ return /^\w([.\/-]?\w+)*$/.test(n) && n.indexOf('o/') !== 0; }

When it happens

Trigger: `git branch <name>` where name contains invalid characters, starts with a symbol, or begins with the o/ prefix.

Common situations: Names with spaces unquoted, names starting with '-' (parsed as option), trying to create 'o/main' manually.

Related errors

• ' + ref + ' is not a branch
• ' + ref + ' is not a remote branch
• ' + branchName + ' is not a branch!
• fatal: HEAD does not point to a branch
• <dynamic branch listing>

AI-assisted analysis of pcottle/learnGitBranching@5b09d0ff96 (2026-08-27). Data as JSON: /api/errors/7d283c823c6cf6ff. Report an issue: GitHub.