Expand description
Stacked branches, for jouet stack: whether each layer really contains
the layer below it, by ancestry and by content.
Ancestry alone is not enough. A restack that resolves a conflict the wrong way, or a rebase that drops a commit, leaves a branch that has its parent’s commits in its history but not their changes in its tree. So every file the parent layer changed is checked in the child’s tree too: the parent’s change, merged into the child’s version of the file, must leave it as it is.
A layer may still change the parent’s lines on purpose, in a commit of its own made on top of them. A file whose version comes from such commits is not flagged; one a merge made is. The cost: a rebase that resolves a conflict by dropping the parent’s lines inside one of the layer’s own commits looks the same as a deliberate edit.
Which branches form the stack, and which PRs have merged, is the caller’s to say (gh-stack’s metadata, or the PRs’ bases on GitHub); this module only reads git. Refs are read as they are: nothing is fetched.
Modules§
- sync
jouet stack sync: bring each layer up to date by merging its parent, bottom first, verifying each merge by ancestry and content before it is committed. Never a rebase, and never a force push.
Structs§
- File
Problem - GhStack
- A stack as gh-stack keeps it.
- Layer
- One layer of a stack, bottom first, as the caller found it.
- Layer
State - One layer as git sees it.
- Stack
- A stack: its layers, bottom first, and where they land.
Enums§
- Problem
- What became of one of the parent’s file changes in the child.
Functions§
- branch_
tip - A branch’s commit: the local branch, which may hold fixes not yet pushed, else the remote’s.
- gh_
stack - The gh-stack stack holding
branch, from thegh-stackfile in the worktree’s git directory or the repository’s common one. None when gh-stack does not track it. - inspect
- Every layer of the stack, as git sees it now.
- missing_
changes - The file changes from
fromtotothat are not intip’s tree. A change is intipwhen merging it intotip’s version of the file leaves that version as it is; a version equal to the one before the change has it reverted. - parent_
base - Where the parent layer’s own changes start: where it branched off its own parent. None for the trunk, whose changes are not checked.
- parent_
tip - The tip of a layer’s parent: the trunk, or the layer below.
- parse_
gh_ stack - The stack holding
branchin the text of agh-stackfile. - remote
- The remote the branches are pushed to:
origin, else the first one. - trunk_
tip - The trunk’s commit: the remote’s, which is what merged PRs land on, else the local branch.