fix(github): omit local-only branches from PR stack comments (#37)

* fix(github): omit local-only branches from PR stack comments

Branches without PRs that don't exist on the remote are now filtered
out of the rendered stack comment and the `[!WARNING]` header. Their
children are promoted up a level so the tree stays connected.

- Add `ListRemoteBranches()` to `git.Git` (reads cached tracking
  refs, no network call)
- `GenerateStackComment` / `renderTree` accept an optional
  `remoteBranches` set; `nil` disables filtering
- `findEffectiveParent()` walks ancestors to find the nearest visible
  parent for the warning header
- Thread the set through `submit` and `sync` command paths

* fix(github): address PR review comments for remote branch filtering

- Add defensive `!isCurrent` guard to `skipNode` in `renderTree`
- Assert WARNING header absent when effective parent is trunk after filtering
- Assert WARNING header references correct non-trunk remote parent
- Add test for multiple consecutive local-only branches being filtered

Author: boneskull

cmd/submit.go

@@ -209,6 +209,18 @@ func doSubmitPRs(g *git.Git, cfg *config.Config, root *tree.Node, branches []*tr
 		}
 	}
 
+	// Build remote branches set for stack comment filtering.
+	// This uses locally-cached tracking refs which are up-to-date after Phase 2 push.
+	var remoteBranches map[string]bool
+	if !dryRun {
+		var rbErr error
+		remoteBranches, rbErr = g.ListRemoteBranches()
+		if rbErr != nil {
+			// Non-fatal: we can still render without filtering
+			fmt.Printf("%s could not list remote branches, stack comments may reference local-only branches: %v\n", s.WarningIcon(), rbErr)
+		}
+	}
+
 	// Collect PR URLs for --web flag
 	var prURLs []string
 
@@ -236,7 +248,7 @@ func doSubmitPRs(g *git.Git, cfg *config.Config, root *tree.Node, branches []*tr
 					}
 				}
 				// Update stack comment
-				if err := ghClient.GenerateAndPostStackComment(root, b.Name, trunk, existingPR); err != nil {
+				if err := ghClient.GenerateAndPostStackComment(root, b.Name, trunk, existingPR, remoteBranches); err != nil {
 					fmt.Printf("%s failed to update stack comment for PR #%d: %v\n", s.WarningIcon(), existingPR, err)
 				}
 
@@ -248,7 +260,7 @@ func doSubmitPRs(g *git.Git, cfg *config.Config, root *tree.Node, branches []*tr
 			if dryRun {
 				fmt.Printf("%s Would create PR for %s (base: %s)\n", s.Muted("dry-run:"), s.Branch(b.Name), s.Branch(parent))
 			} else {
-				prNum, adopted, err := createPRForBranch(g, ghClient, cfg, root, b.Name, parent, trunk, s)
+				prNum, adopted, err := createPRForBranch(g, ghClient, cfg, root, b.Name, parent, trunk, remoteBranches, s)
 				if err != nil {
 					fmt.Printf("%s failed to create PR for %s: %v\n", s.WarningIcon(), s.Branch(b.Name), err)
 				} else if adopted {
@@ -284,7 +296,7 @@ func doSubmitPRs(g *git.Git, cfg *config.Config, root *tree.Node, branches []*tr
 // createPRForBranch creates a PR for the given branch and stores the PR number.
 // If a PR already exists for the branch, it adopts the existing PR instead.
 // Returns (prNumber, adopted, error) where adopted is true if we adopted an existing PR.
-func createPRForBranch(g *git.Git, ghClient *github.Client, cfg *config.Config, root *tree.Node, branch, base, trunk string, s *style.Style) (int, bool, error) {
+func createPRForBranch(g *git.Git, ghClient *github.Client, cfg *config.Config, root *tree.Node, branch, base, trunk string, remoteBranches map[string]bool, s *style.Style) (int, bool, error) {
 	// Determine if draft (not targeting trunk = middle of stack)
 	draft := base != trunk
 
@@ -309,7 +321,7 @@ func createPRForBranch(g *git.Git, ghClient *github.Client, cfg *config.Config,
 	if err != nil {
 		// Check if PR already exists - if so, adopt it
 		if strings.Contains(err.Error(), "pull request already exists") {
-			prNum, adoptErr := adoptExistingPR(ghClient, cfg, root, branch, base, trunk, s)
+			prNum, adoptErr := adoptExistingPR(ghClient, cfg, root, branch, base, trunk, remoteBranches, s)
 			return prNum, true, adoptErr
 		}
 		return 0, false, err
@@ -326,7 +338,7 @@ func createPRForBranch(g *git.Git, ghClient *github.Client, cfg *config.Config,
 	}
 
 	// Add stack navigation comment
-	if err := ghClient.GenerateAndPostStackComment(root, branch, trunk, pr.Number); err != nil {
+	if err := ghClient.GenerateAndPostStackComment(root, branch, trunk, pr.Number, remoteBranches); err != nil {
 		fmt.Printf("%s failed to add stack comment to PR #%d: %v\n", s.WarningIcon(), pr.Number, err)
 	}
 
@@ -435,7 +447,7 @@ func promptForPRDetails(branch, defaultTitle, defaultBody string, s *style.Style
 }
 
 // adoptExistingPR finds an existing PR for the branch and adopts it into the stack.
-func adoptExistingPR(ghClient *github.Client, cfg *config.Config, root *tree.Node, branch, base, trunk string, s *style.Style) (int, error) {
+func adoptExistingPR(ghClient *github.Client, cfg *config.Config, root *tree.Node, branch, base, trunk string, remoteBranches map[string]bool, s *style.Style) (int, error) {
 	existingPR, err := ghClient.FindPRByHead(branch)
 	if err != nil {
 		return 0, fmt.Errorf("failed to find existing PR: %w", err)
@@ -462,7 +474,7 @@ func adoptExistingPR(ghClient *github.Client, cfg *config.Config, root *tree.Nod
 	}
 
 	// Add/update stack navigation comment
-	if err := ghClient.GenerateAndPostStackComment(root, branch, trunk, existingPR.Number); err != nil {
+	if err := ghClient.GenerateAndPostStackComment(root, branch, trunk, existingPR.Number, remoteBranches); err != nil {
 		fmt.Printf("%s failed to update stack comment: %v\n", s.WarningIcon(), err)
 	}
 

cmd/sync.go

@@ -34,7 +34,7 @@ func init() {
 }
 
 // updateStackComments updates the navigation comment on all PRs in the stack.
-func updateStackComments(cfg *config.Config, gh *github.Client, s *style.Style) error {
+func updateStackComments(cfg *config.Config, g *git.Git, gh *github.Client, s *style.Style) error {
 	trunk, err := cfg.GetTrunk()
 	if err != nil {
 		return err
@@ -53,13 +53,20 @@ func updateStackComments(cfg *config.Config, gh *github.Client, s *style.Style)
 		prInfo = make(map[int]github.PRInfo)
 	}
 
+	// Build remote branches set for filtering local-only branches
+	remoteBranches, rbErr := g.ListRemoteBranches()
+	if rbErr != nil {
+		// Non-fatal: render without filtering
+		fmt.Printf("%s could not list remote branches: %v\n", s.WarningIcon(), rbErr)
+	}
+
 	// Walk tree and update each PR's comment
-	return walkTreeAndUpdateComments(root, root, trunk, gh, prInfo, s)
+	return walkTreeAndUpdateComments(root, root, trunk, gh, prInfo, remoteBranches, s)
 }
 
-func walkTreeAndUpdateComments(node, root *tree.Node, trunk string, gh *github.Client, prInfo map[int]github.PRInfo, s *style.Style) error {
+func walkTreeAndUpdateComments(node, root *tree.Node, trunk string, gh *github.Client, prInfo map[int]github.PRInfo, remoteBranches map[string]bool, s *style.Style) error {
 	if node.PR > 0 {
-		comment := github.GenerateStackComment(root, node.Name, trunk, gh.RepoURL(), prInfo)
+		comment := github.GenerateStackComment(root, node.Name, trunk, gh.RepoURL(), prInfo, remoteBranches)
 		if comment != "" {
 			if err := gh.CreateOrUpdateStackComment(node.PR, comment); err != nil {
 				fmt.Printf("%s failed to update comment on PR #%d: %v\n", s.WarningIcon(), node.PR, err)
@@ -69,7 +76,7 @@ func walkTreeAndUpdateComments(node, root *tree.Node, trunk string, gh *github.C
 	}
 
 	for _, child := range node.Children {
-		if err := walkTreeAndUpdateComments(child, root, trunk, gh, prInfo, s); err != nil {
+		if err := walkTreeAndUpdateComments(child, root, trunk, gh, prInfo, remoteBranches, s); err != nil {
 			return err
 		}
 	}
@@ -355,7 +362,7 @@ func runSync(cmd *cobra.Command, args []string) error {
 	// Update stack comments on all PRs
 	if !syncDryRunFlag {
 		fmt.Println("\nUpdating stack comments...")
-		if err := updateStackComments(cfg, gh, s); err != nil {
+		if err := updateStackComments(cfg, g, gh, s); err != nil {
 			fmt.Printf("%s failed to update some comments: %v\n", s.WarningIcon(), err)
 		}
 	}

internal/git/git.go

@@ -225,6 +225,24 @@ func (g *Git) RemoteBranchExists(branch string) bool {
 	return err == nil
 }
 
+// ListRemoteBranches returns the set of branch names that exist on origin,
+// based on locally-cached remote-tracking refs (no network call).
+// This is accurate as long as a fetch or push has been done recently.
+func (g *Git) ListRemoteBranches() (map[string]bool, error) {
+	out, err := g.run("for-each-ref", "--format=%(refname:strip=3)", "refs/remotes/origin/")
+	if err != nil {
+		return nil, err
+	}
+	branches := make(map[string]bool)
+	for _, line := range strings.Split(out, "\n") {
+		line = strings.TrimSpace(line)
+		if line != "" && line != "HEAD" {
+			branches[line] = true
+		}
+	}
+	return branches, nil
+}
+
 // RebaseOnto rebases a branch onto a new base, replaying only commits after oldBase.
 // Checks out the branch first, then runs: git rebase --onto <newBase> <oldBase>
 // Useful when a parent branch was squash-merged and we need to replay only

internal/github/comments.go

@@ -18,7 +18,11 @@ const StackCommentMarker = "<!-- gh-stack:nav -->"
 //
 // Only the current stack is rendered: the path from root to the current branch,
 // plus all descendants of the current branch. Sibling stacks are excluded.
-func GenerateStackComment(root *tree.Node, currentBranch, trunk, repoURL string, prInfo map[int]PRInfo) string {
+//
+// If remoteBranches is non-nil, branches without PRs that don't exist on the
+// remote are omitted (their children are promoted up a level). Pass nil to
+// disable this filtering.
+func GenerateStackComment(root *tree.Node, currentBranch, trunk, repoURL string, prInfo map[int]PRInfo, remoteBranches map[string]bool) string {
 	var sb strings.Builder
 
 	// Find the current node
@@ -40,13 +44,18 @@ func GenerateStackComment(root *tree.Node, currentBranch, trunk, repoURL string,
 	sb.WriteString(StackCommentMarker)
 	sb.WriteString("\n")
 
+	// Find the effective parent: the nearest ancestor that would be visible
+	// in the rendered tree. A node is visible if it has a PR, exists on the
+	// remote, or remote filtering is disabled.
+	effectiveParent := findEffectiveParent(currentNode, remoteBranches)
+
 	// Add warning if not targeting trunk
-	if currentNode.Parent != nil && currentNode.Parent.Name != trunk {
+	if effectiveParent != nil && effectiveParent.Name != trunk {
 		sb.WriteString("> [!WARNING]\n")
-		sb.WriteString(fmt.Sprintf("> This PR is part of a stack and targets branch `%s`, not `%s`.\n", currentNode.Parent.Name, trunk))
+		sb.WriteString(fmt.Sprintf("> This PR is part of a stack and targets branch `%s`, not `%s`.\n", effectiveParent.Name, trunk))
 
 		// Build parent PR reference if available
-		parentPR := currentNode.Parent.PR
+		parentPR := effectiveParent.PR
 		if parentPR > 0 {
 			parentURL := fmt.Sprintf("%s/pull/%d", repoURL, parentPR)
 			linkText := fmt.Sprintf("#%d", parentPR)
@@ -63,7 +72,7 @@ func GenerateStackComment(root *tree.Node, currentBranch, trunk, repoURL string,
 	sb.WriteString("### :books: Pull Request Stack\n\n")
 
 	// Render tree from root as nested markdown list, filtered to current stack
-	renderTree(&sb, root, currentBranch, repoURL, prInfo, 0, ancestorPath)
+	renderTree(&sb, root, currentBranch, repoURL, prInfo, 0, ancestorPath, remoteBranches)
 
 	sb.WriteString("\n---\n")
 	sb.WriteString("*Managed by [gh-stack](https://github.com/boneskull/gh-stack)*\n")
@@ -87,44 +96,70 @@ func collectPRNumbersRecursive(node *tree.Node, numbers *[]int) {
 	}
 }
 
+// findEffectiveParent walks up from a node's parent to find the nearest ancestor
+// that would be rendered in the comment. A node is "visible" if it has a PR or
+// exists on the remote (or if remote filtering is disabled). Returns nil if the
+// node has no parent (i.e., it's the root).
+func findEffectiveParent(node *tree.Node, remoteBranches map[string]bool) *tree.Node {
+	for p := node.Parent; p != nil; p = p.Parent {
+		if p.PR > 0 || remoteBranches == nil || remoteBranches[p.Name] {
+			return p
+		}
+	}
+	return nil
+}
+
 // renderTree recursively renders the tree structure as nested markdown lists.
 //
 // The ancestorPath set controls which children are rendered at each level:
 //   - For nodes that are ancestors of the current branch (on the path but not
 //     the current branch itself), only the child on the ancestor path is shown.
 //   - For the current branch and all its descendants, all children are shown.
 //
-// This ensures only the current stack is rendered, not sibling stacks.
-func renderTree(sb *strings.Builder, node *tree.Node, currentBranch, repoURL string, prInfo map[int]PRInfo, depth int, ancestorPath map[string]bool) {
-	// Build prefix based on depth (2 spaces per level for markdown nested lists)
-	prefix := strings.Repeat("  ", depth) + "- "
-
+// If remoteBranches is non-nil, nodes without PRs that aren't on the remote
+// are collapsed: their children are rendered at the skipped node's depth
+// instead of being indented further. This prevents local-only branches from
+// appearing in the GitHub comment.
+func renderTree(sb *strings.Builder, node *tree.Node, currentBranch, repoURL string, prInfo map[int]PRInfo, depth int, ancestorPath map[string]bool, remoteBranches map[string]bool) {
 	isCurrent := node.Name == currentBranch
 
-	// Format: "[Title #N](url) - branch: `name`" or "branch: `name`" if no PR
-	if node.PR > 0 {
-		prURL := fmt.Sprintf("%s/pull/%d", repoURL, node.PR)
-		linkText := fmt.Sprintf("#%d", node.PR)
-		if info, ok := prInfo[node.PR]; ok && info.Title != "" {
-			linkText = fmt.Sprintf("%s #%d", info.Title, node.PR)
-		}
+	// Skip branches that have no PR and don't exist on the remote.
+	// The current branch is never skipped (defensive: it should always have
+	// a PR since we're generating a comment for it, but just in case).
+	// When remoteBranches is nil, no filtering is applied.
+	skipNode := node.PR == 0 && !isCurrent && remoteBranches != nil && !remoteBranches[node.Name]
+
+	nextDepth := depth
+	if !skipNode {
+		// Build prefix based on depth (2 spaces per level for markdown nested lists)
+		prefix := strings.Repeat("  ", depth) + "- "
+
+		// Format: "[Title #N](url) - branch: `name`" or "branch: `name`" if no PR
+		if node.PR > 0 {
+			prURL := fmt.Sprintf("%s/pull/%d", repoURL, node.PR)
+			linkText := fmt.Sprintf("#%d", node.PR)
+			if info, ok := prInfo[node.PR]; ok && info.Title != "" {
+				linkText = fmt.Sprintf("%s #%d", info.Title, node.PR)
+			}
 
-		if isCurrent {
-			// Bold the link for current PR
-			fmt.Fprintf(sb, "%s**[%s](%s)** - branch: `%s` *(this PR)*", prefix, linkText, prURL, node.Name)
-		} else {
-			fmt.Fprintf(sb, "%s[%s](%s) - branch: `%s`", prefix, linkText, prURL, node.Name)
-		}
-	} else {
-		// No PR - show "branch: `name`"
-		if isCurrent {
-			fmt.Fprintf(sb, "%s**branch: `%s`** *(this PR)*", prefix, node.Name)
+			if isCurrent {
+				// Bold the link for current PR
+				fmt.Fprintf(sb, "%s**[%s](%s)** - branch: `%s` *(this PR)*", prefix, linkText, prURL, node.Name)
+			} else {
+				fmt.Fprintf(sb, "%s[%s](%s) - branch: `%s`", prefix, linkText, prURL, node.Name)
+			}
 		} else {
-			fmt.Fprintf(sb, "%sbranch: `%s`", prefix, node.Name)
+			// No PR - show "branch: `name`"
+			if isCurrent {
+				fmt.Fprintf(sb, "%s**branch: `%s`** *(this PR)*", prefix, node.Name)
+			} else {
+				fmt.Fprintf(sb, "%sbranch: `%s`", prefix, node.Name)
+			}
 		}
-	}
 
-	sb.WriteString("\n")
+		sb.WriteString("\n")
+		nextDepth = depth + 1
+	}
 
 	// For ancestor nodes (above the current branch), only render the child
 	// that leads to the current branch. For the current branch and its
@@ -134,7 +169,7 @@ func renderTree(sb *strings.Builder, node *tree.Node, currentBranch, repoURL str
 		if isAncestorAboveCurrent && !ancestorPath[child.Name] {
 			continue
 		}
-		renderTree(sb, child, currentBranch, repoURL, prInfo, depth+1, ancestorPath)
+		renderTree(sb, child, currentBranch, repoURL, prInfo, nextDepth, ancestorPath, remoteBranches)
 	}
 }
 
@@ -177,7 +212,10 @@ func (c *Client) CreateOrUpdateStackComment(prNumber int, body string) error {
 
 // GenerateAndPostStackComment generates and posts/updates a stack comment for a PR.
 // It fetches PR titles via GraphQL and renders the full comment.
-func (c *Client) GenerateAndPostStackComment(root *tree.Node, branch, trunk string, prNumber int) error {
+//
+// If remoteBranches is non-nil, branches without PRs that don't exist on the
+// remote are omitted from the rendered comment. Pass nil to disable filtering.
+func (c *Client) GenerateAndPostStackComment(root *tree.Node, branch, trunk string, prNumber int, remoteBranches map[string]bool) error {
 	// Collect all PR numbers from the tree
 	prNumbers := CollectPRNumbers(root)
 
@@ -188,7 +226,7 @@ func (c *Client) GenerateAndPostStackComment(root *tree.Node, branch, trunk stri
 		prInfo = make(map[int]PRInfo)
 	}
 
-	comment := GenerateStackComment(root, branch, trunk, c.RepoURL(), prInfo)
+	comment := GenerateStackComment(root, branch, trunk, c.RepoURL(), prInfo, remoteBranches)
 	if comment == "" {
 		return nil
 	}