pcottle/learnGitBranching · error · GitError

fatal: A branch named ' + newName + ' already exists.

Error message

fatal: A branch named ' + newName + ' already exists.

What it means

Thrown by renameBranch(oldName, newName, force) when the new name already exists (doesRefExist) and force was not passed. Real git behaves identically: branch -m refuses to clobber an existing branch without -M/-f. Message is currently untranslated (intl.todo).

Source

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

  }

  if (target.getIsRemote()) {
    throw new GitError({
      msg: intl.str('git-error-remote-branch')
    });
  }

  newName = this.validateBranchName(newName);

  if (this.doesRefExist(newName)) {
    if (!force) {
      throw new GitError({
        msg: intl.todo("fatal: A branch named '" + newName + "' already exists.")
      });
    }
    var existing = this.resolveID(newName);
    if (existing.get('type') !== 'branch') {
      throw new GitError({
        msg: intl.str('git-error-options')
      });
    }
    if (this.HEAD.get('target') === existing) {
      throw new GitError({
        msg: intl.str('git-error-branch')
      });
    }
    this.deleteBranch(existing);
  }

  var oldBranch = target;
  var commitTarget = oldBranch.get('target');
  var newBranch = this.makeBranch(newName, commitTarget);

  if (oldBranch.get('remoteTrackingBranchID')) {
    newBranch.set('remoteTrackingBranchID', oldBranch.get('remoteTrackingBranchID'));
  }

View on GitHub (pinned to 5b09d0ff96)

Solutions

1. Choose a fresh target name
2. Delete the conflicting branch first
3. Pass force=true (equivalent to git branch -M) — note it still refuses when the existing ref is not a branch or is checked out by HEAD

Example fix

// before
engine.renameBranch('dev', 'main');
// after
engine.renameBranch('dev', 'main', true); // git branch -M

if (engine.doesRefExist(newName) && !force) { /* pass force=true or pick new name */ }

When it happens

Trigger: renameBranch('a','b') without force=true while branch (or tag) 'b' already exists.

Common situations: Renaming onto main or another long-lived branch accidentally; scripting renames without checking targets; stale branch name collisions.

Related errors

• fatal: HEAD does not point to a branch
• git-error-branch
• fatal: not a branch:
• fatal: not a branch: ' + oldName
• ' + ref + ' is not a branch

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