Scope

One flag says how much of the structure a command means, and it means the same thing whichever record describes the branch.

--scope	selects
branch	just this branch
path	the trunk down to this branch
subtree	this branch and everything above it
stack	this whole stack, trunk to tips
trunk	every stack on this trunk
all	every stack in the repository (status and prune only)

Selected from a trunk, stack is the whole tree under it.

A lattice, not a list

The values are two halves, toward the trunk and toward the tips, taken separately, together, or neither:

              all          every trunk's stacks   (read-only commands)
               │
             trunk         my trunk and everything under it, cousins included
               │
             stack         trunk → me → my descendants
             ╱   ╲
        path       subtree
    (trunk → me)  (me → my descendants)
             ╲   ╱
            branch         just me

Each value answers something a person says:

value	the sentence
branch	“just rebase me onto my parent, I’ll deal with the rest later”
path	“what does GitHub need to see below me”
subtree	“my parent’s conflict can wait; get everything above me sitting cleanly”
stack	“show me where I am”
trunk	“the trunk moved, bring everything on it up to date”
all	“show me every stack in this repository”

stack is what a person means by “my stack”: the path down to the trunk and everything above, leaving out the cousins that merely share a trunk.

Defaults differ because the commands differ

• status and github status default to stack. Reading is free, so show where you are, ancestors and descendants both.
• restack defaults to subtree, because rewriting is not free. A conflict below you may be one you are deliberately deferring, and replaying it uninvited is how restacking from the middle walks into it every time.
• land defaults to path, because standing in the middle of a stack and typing land means “as far as here”.
• prune defaults to stack and offers all, since it edits only the record and forgets only what has landed.
• pull offers only stack and trunk. It advances the base and replays what sits on it, so anything narrower would leave the branches below on the old base.
• untrack offers only branch (its default) and subtree.

g2g status                   # where am I: the trunk, me, and everything above
g2g status --scope path      # just the trunk down to me
g2g restack --apply          # me and what depends on me
g2g status --scope all       # every stack in the repository

A command refuses any scope it does not offer. all is offered only where nothing is rewritten: the read-only commands, and prune. It spans trunks, and a rewrite acts on one. restack does offer trunk, and a rewrite that wide is the likeliest to reach a branch checked out in another worktree, which it then refuses by name.

restack’s default is wider than it once was, and that is not a surprise, because restack previews by default: widening the default widens what you read before agreeing to it.

Publishing is linear

A GitHub native stack is linear, so push, submit, land, github link, github unlink and github retarget take stack or path only, and refuse a selection that forks, naming the remedy rather than choosing a line.

Selecting a leaf is that remedy, and it needs no flag. A leaf has no descendants, so stack collapses to an ordered path by itself.

This is a capability of publishing, not a property of scope. Selecting a subtree to look at does not imply a subtree can be published as a GitHub native stack.

github comment has no --scope. It always keeps the whole stack the branch belongs to, because each comment draws the stack from its own pull request, and keeping only part of it would leave the rest describing a different one. See GitHub.

--no-stack is gone

The older --no-stack flag is now --scope branch. Keeping both would have meant two flags that overlapped, and the overlap was where their meanings drifted apart.

Further reading

design-docs/stack-scope.md records why the axis looks the way it does.