{"record":{"id":"4a46895c91e33f58","repo":"pcottle/learnGitBranching","slug":"git-error-remote-branch","errorCode":null,"errorMessage":"git-error-remote-branch","messagePattern":"git-error-remote-branch","errorType":"validation","errorClass":"GitError","httpStatus":null,"severity":"error","filePath":"src/js/git/index.js","lineNumber":2706,"sourceCode":"  this.HEAD.set('target', target);\n};\n\nGitEngine.prototype.forceBranch = function(branchName, where) {\n  branchName = this.crappyUnescape(branchName);\n  // if branchname doesn't exist...\n  if (!this.doesRefExist(branchName)) {\n    this.branch(branchName, where);\n  }\n\n  var branch = this.resolveID(branchName);\n\n  if (branch.get('type') !== 'branch') {\n    throw new GitError({\n      msg: intl.str('git-error-options')\n    });\n  }\n  if (branch.getIsRemote()) {\n    throw new GitError({\n      msg: intl.str('git-error-remote-branch')\n    });\n  }\n\n  var whereCommit = this.getCommitFromRef(where);\n\n  this.setTargetLocation(branch, whereCommit);\n};\n\nGitEngine.prototype.branch = function(name, ref) {\n  var target = this.getCommitFromRef(ref);\n  var newBranch = this.validateAndMakeBranch(name, target);\n\n  ref = this.resolveID(ref);\n  if (this.isRemoteBranchRef(ref)) {\n    this.setLocalToTrackRemote(newBranch, ref);\n  }\n};","sourceCodeStart":2688,"sourceCodeEnd":2724,"githubUrl":"https://github.com/pcottle/learnGitBranching/blob/5b09d0ff9678cad164f5a7488a279a44f90d7256/src/js/git/index.js#L2688-L2724","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check out the local branch name (main, not o/main)","Create a local branch tracking the remote one first (git checkout -b main o/main style flow)","Fetch/merge the remote ref instead of checking it out"],"exampleFix":"// before\ngit checkout o/main\n// after\ngit checkout main","handlingStrategy":"type-guard","validationCode":"var r = engine.resolveID(name);\nif (r && r.getIsRemote()) throw new Error('remote-tracking ref; use local branch');","typeGuard":"function isLocalBranch(engine, name) {\n  var r = engine.resolveID(name);\n  return !!r && r.get('type') === 'branch' && !r.getIsRemote();\n}","tryCatchPattern":null,"preventionTips":["Never checkout o/* refs directly","Create a local branch from the tracking ref instead"],"tags":["git","remote","remote-tracking-branch","checkout"],"backgroundTag":"git-checkout-remote-tracking-branch","analyzedSha":"5b09d0ff9678cad164f5a7488a279a44f90d7256","analyzedAt":"2026-08-27T13:53:49.057Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}