pcottle/learnGitBranching · error · GitError

Fatal: no tags found upstream

Error message

Fatal: no tags found upstream

What it means

Thrown by the describe implementation when it walks upstream from the target commit through sorted parents and never encounters a commit carrying a tag. Real git describe fails the same way when no annotated tag is reachable from the commit, and the simulator surfaces intl.todo('Fatal: no tags found upstream').

Source

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

  while (pQueue.length) {
    var popped = pQueue.pop();
    var thisID = popped.get('id');
    if (tagMap[thisID]) {
      foundTag = tagMap[thisID];
      break;
    }
    // ok keep going
    numAway.push(popped.get('id'));

    var parents = popped.get('parents');
    if (parents && parents.length) {
      pQueue = pQueue.concat(parents);
      pQueue.sort(this.dateSortFunc);
    }
  }

  if (!foundTag) {
    throw new GitError({
      msg: intl.todo('Fatal: no tags found upstream')
    });
  }

  if (numAway.length === 0) {
    throw new CommandResult({
      msg: foundTag
    });
  }

  // then join
  throw new CommandResult({
    msg: foundTag + '-' + numAway.length + '-g' + startCommit.get('id')
  });
};

GitEngine.prototype.renameBranch = function(oldName, newName, force) {
  var target = this.resolveID(oldName);

View on GitHub (pinned to 5b09d0ff96)

Solutions

1. Create a tag on some ancestor commit first (git tag <name> <commit>) then retry describe
2. Verify the tag is on the current branch's history, not on an unrelated branch
3. If you need a descriptor without tags, use a fallback like the short commit hash

Example fix

// before
git describe
// after
git tag v1.0 C2
git describe

function hasUpstreamTag(engine, commit) {
  var queue = [commit], seen = {};
  while (queue.length) {
    var c = queue.shift();
    if (c.get('tags').length) return true;
    c.get('parents').forEach(function(p){ if(!seen[p.get('id')]) { seen[p.get('id')]=1; queue.push(p); } });
  }
  return false;
}

try { engine.describe(ref); } catch (e) { if (e instanceof GitError) { /* fall back to short sha */ } else throw e; }

When it happens

Trigger: Calling describe (git describe) on a commit whose ancestry contains zero tags — e.g. a fresh repository with only commits and branches, no tags ever created, or a commit on an orphan history.

Common situations: Running git describe before creating any tag; levels/exercises that never set up tags; describing a commit on a side history disconnected from the tagged one.

Related errors

• git-error-already-exists
• fatal: No tags found, cannot describe anything.
• No tag found, nothing to remove
• bad-tag-name
• <dynamic tag listing>

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