pcottle/learnGitBranching · error · GitError

git-error-remote-branch

Error message

git-error-remote-branch

What it means

Branch-consumer guard immediately after #58: even a genuine branch ref is rejected if it is a remote-tracking branch (getIsRemote() true, i.e. o/main style refs). You cannot check out or otherwise operate on remote-tracking refs as if they were local branches.

Source

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

  this.HEAD.set('target', target);
};

GitEngine.prototype.forceBranch = function(branchName, where) {
  branchName = this.crappyUnescape(branchName);
  // if branchname doesn't exist...
  if (!this.doesRefExist(branchName)) {
    this.branch(branchName, where);
  }

  var branch = this.resolveID(branchName);

  if (branch.get('type') !== 'branch') {
    throw new GitError({
      msg: intl.str('git-error-options')
    });
  }
  if (branch.getIsRemote()) {
    throw new GitError({
      msg: intl.str('git-error-remote-branch')
    });
  }

  var whereCommit = this.getCommitFromRef(where);

  this.setTargetLocation(branch, whereCommit);
};

GitEngine.prototype.branch = function(name, ref) {
  var target = this.getCommitFromRef(ref);
  var newBranch = this.validateAndMakeBranch(name, target);

  ref = this.resolveID(ref);
  if (this.isRemoteBranchRef(ref)) {
    this.setLocalToTrackRemote(newBranch, ref);
  }
};

View on GitHub (pinned to 5b09d0ff96)

Solutions

1. Check out the local branch name (main, not o/main)
2. Create a local branch tracking the remote one first (git checkout -b main o/main style flow)
3. Fetch/merge the remote ref instead of checking it out

Example fix

// before
git checkout o/main
// after
git checkout main

var r = engine.resolveID(name);
if (r && r.getIsRemote()) throw new Error('remote-tracking ref; use local branch');

function isLocalBranch(engine, name) {
  var r = engine.resolveID(name);
  return !!r && r.get('type') === 'branch' && !r.getIsRemote();
}

When it happens

Trigger: Calling the branch-consuming API (e.g. checkout/branch delete) with a name like 'o/main' where branch.getIsRemote() returns true — checking out a remote-tracking branch directly.

Common situations: Typing git checkout o/main instead of git checkout main; level solutions confusing the tracking ref with the local branch; forgetting to create a local branch off the remote one.

Related errors

• cannot fetch to ' + ref + ' when checked out on ' + ref
• ' + ref + ' is not a remote branch
• ' + generalArgs[0] + ' is not a remote in your repository! t
• git-error-origin-required
• git-result-nothing

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