Module stack 

Stack metadata: the branch.<name>.stkParent/stkBase annotations and the structural queries built on them. Navigation lives in [nav], the rebase engine in restack.

Enums

NavOutput

How a navigation command reports where it landed.

Functions

abort_restack

adopt_branch

apply_remote_metadata

Rebuild local stack metadata from the shared ref, fetching any listed branch that is not present locally. Returns how many branches it attached.

behind_parent_hint

A restack nudge when branch is missing commits from its parent’s tip. Local-only; a missing parent yields nothing.

branch_and_descendants

branch_parents

(branch, parent) pairs for the branches that stack on something. A branch with no recorded parent is skipped, and so is a floor - it is the base the stack sits on, whatever parent it may have picked up, and callers use this to decide what to write to (review bodies, the metadata ref).

checkout_bottom

Check out the bottom of the current stack: the branch just above the trunk. From the trunk itself, a single stacked child is unambiguous.

checkout_child

Walk distance branches up, towards the leaf, prompting at each fork the way top does. up <branch> names a child instead and always moves one.

checkout_parent

Walk distance branches down, towards the trunk.

checkout_top

Check out the leaf of the current stack, following single children. A fork is ambiguous, like up without a branch.

clear_floor

clear_renamed_from

Drop the rename marker once its review has been handled.

continue_restack

create_branch

create_branch_in_worktree

Create branch in a new worktree of its own instead of checking it out here, leaving the current worktree on the branch it was already on.

current_stack_branches

Every branch in the stack branch belongs to, trunk excluded: the whole subtree under the stack’s base (so fork siblings are included too), unlike stack_line which is only branch’s own line. The base is the bottom of branch’s line - its topmost non-trunk ancestor - so sibling stacks that merely share the trunk are left out, exactly as they are for stack_line. For an unanchored stack the base is its real root branch, itself stacked, so it stays in.

detach_branch

insert_branch

Insert a new empty branch directly above the current one, moving the current branch’s children onto it. The new branch shares the current tip, so descendants stay correctly based; commit to it, then restack to replay them. Any uncommitted changes ride onto the new branch, like new.

is_floor

Whether branch is a stack floor - see [FLOOR_KEY].

listed_branches

The branches list may annotate with review info: the current stack, or - with all - every stacked branch. A superset of what the tree actually draws is fine here; its only job is to bound which branches get a per-branch review lookup, so list never queries every open PR in the repo.

mark_floor

Record branch as a stack floor. Best effort: a floor that fails to record is still derived from the shape while branches sit on it, so a failure here costs persistence, not protection.

owned_worktree

The worktree git-stk created for branch, if it created one and it is still there. Only these are ours to remove.

path_from_root

The stack path from the bottom up to (and including) branch, parent-first; descendants above it are left out.

prepend_branch

Insert a new empty branch directly below the current one, moving the current branch onto it. Branches from the current branch’s parent, so it requires a clean worktree. Commit to it, then restack.

print_all_stacks

Print every stack, not just the current one, each as its own block separated by a blank line. Stacks that merely share the trunk are drawn separately - one per direct trunk child - each repeating the trunk as its base, so they read as distinct piles rather than one tangled tree. Rootless fragments print above the trunk-anchored ones. The branch you are on is marked wherever it appears.

print_children

print_parent

print_stack

publish_metadata

Publish the current stack’s parent map to the shared metadata ref so another clone can rebuild it. Best effort: a failure warns but never aborts the push that triggered it.

record_base

Record the fork point between a branch and its parent (best effort; e.g. unrelated histories have no merge base, which is not an error here).

recorded_worktree

What the marker says, whether or not the directory still exists. repair needs the raw value to spot a marker pointing at nothing.

rename_branch

Rename a branch and keep the stack intact. Git moves the branch’s own metadata with the rename; children pointing at the old name are retargeted here.

renamed_from

The branch branch was renamed from, if a replaced review is still pending.

restack

set_owned_worktree

Record that git-stk owns branch’s worktree at path.

set_renamed_from

Record that branch is the rename of old, whose open review the next submit should replace and close.

snapshot

Record the current stack so undo can restore it. The label names the operation being undone. No-ops after the first call in a process, and is best effort: a snapshot failure never blocks the command itself.

stack_line

Every branch in the stack containing branch, parent-first: the line from the stack bottom up through branch, plus everything above it. Sibling stacks that share only the trunk are left out - they branch off the trunk separately, not through branch. The trunk itself is excluded; an unanchored root stays in (path_from_root keeps it).

stack_root

The root of the stack containing branch (the base everything sits on).

stacked_layers

The branches in line that actually stack on something - those with a recorded parent. A line rooted off the trunk keeps its parentless root (see path_from_root), and that root is the base the branch above it targets, not a layer of the stack: nothing submits, pushes, or merges it. restack and absorb already skip it; this is how the rest agree.

trunk_branch

The trunk branch: the remote’s default branch when known locally, otherwise a conventional name that exists.

trunk_held_elsewhere

Whether the trunk cannot be fetched because another worktree has it checked out, reporting the skip when so.

unanchored_base

The base branches sits on, when that is a branch rather than the trunk: the parentless root of a line rooted off-trunk, with layers stacked on it. It is not part of the stack - nothing submits, pushes, merges, or re-parents it - so callers hold it out of whatever they are about to do.

undo

Restore the most recent snapshot: reset branch tips and metadata to their pre-mutation state. Refuses on a dirty worktree (it resets the current branch) and consumes the snapshot so it is one-shot.

unset_owned_worktree

Forget that git-stk owns a worktree for branch.