stack

Documentation

Overview

Package stack implements plain-git stacked branch helpers. Parents resolve from PR base → local config → dot-depth name → trunk.

Index

• func DotBranchDepth(b string) int
• func FormatList(root string, infos []BranchInfo) string
• type BranchInfo
  • func OrderAsTree(infos []BranchInfo) []BranchInfo
• type BranchStatus
• type CreateOpts
• type DeleteOpts
• type Engine
  • func (e *Engine) Adopt(root string) error
  • func (e *Engine) AncestorChainTo(branch string) ([]string, error)
  • func (e *Engine) BranchDepth(branch string) int
  • func (e *Engine) BranchNeedsRestack(branch, parent, parentRefOverride string) bool
  • func (e *Engine) Create(opts CreateOpts) error
  • func (e *Engine) DeleteLocal(opts DeleteOpts) error
  • func (e *Engine) DescendantsOf(root string) ([]string, error)
  • func (e *Engine) DivergePlaybook(branch string) string
  • func (e *Engine) EnsureRemoteReady(branch string) error
  • func (e *Engine) FetchIfNeeded(noFetch bool) error
  • func (e *Engine) InvalidateParentCache()
  • func (e *Engine) IsTrunk(name string) bool
  • func (e *Engine) List(root string) ([]BranchInfo, error)
  • func (e *Engine) LoadParents(opts LoadParentsOpts) error
  • func (e *Engine) MaybePush(branch string, doPush bool) error
  • func (e *Engine) PRStackBranches(branch string) []string
  • func (e *Engine) Parent(branch string) (string, error)
  • func (e *Engine) ParentOf(branch string) string
  • func (e *Engine) ParentOfWithSource(branch string) (string, ParentSource)
  • func (e *Engine) Pull(branch string) error
  • func (e *Engine) Reparent(opts ReparentOpts) error
  • func (e *Engine) Restack(opts RestackOpts) error
  • func (e *Engine) RestackBranch(branch, parent, parentRefOverride string) error
  • func (e *Engine) RestackUpstream(parentRef, branchRef string) (string, error)
  • func (e *Engine) SetParentLocal(branch, parent string) error
  • func (e *Engine) SlashRefConflict(name string) (string, bool)
  • func (e *Engine) SortByDepth(branches []string) []string
  • func (e *Engine) Sync(opts SyncOpts) (*SyncResult, error)
  • func (e *Engine) Track(branch, parent string) error
  • func (e *Engine) TrunkRef() (string, error)
  • func (e *Engine) Untrack(branch string) error
• type LoadParentsOpts
• type ParentSource
• type PlanRow
• type ReparentOpts
• type RestackOpts
• type SyncOpts
• type SyncResult

Functions

func DotBranchDepth

func DotBranchDepth(b string) int

DotBranchDepth is number of '.' + 1 (legacy name helper for display fallback).

func FormatList

func FormatList(root string, infos []BranchInfo) string

FormatList prints ls-style lines with ASCII tree connectors and aligned columns.

Types

type BranchInfo

type BranchInfo struct {
	Name       string
	Parent     string
	ShortSHA   string
	OwnCommits string
	Status     BranchStatus
	Depth      int
	Remote     git.RemoteRelation
	// TreePrefix is ASCII connectors, e.g. "│   ├─ " (set by OrderAsTree).
	TreePrefix string
}

BranchInfo is one row in the stack tree.

func OrderAsTree

func OrderAsTree(infos []BranchInfo) []BranchInfo

OrderAsTree reorders infos into DFS tree order and sets TreePrefix (├─ └─ │) based on parent relationships among the listed branches.

type BranchStatus

type BranchStatus string

BranchStatus is status for ls / TUI.

const (
	StatusOK            BranchStatus = "ok"
	StatusNeedsRestack  BranchStatus = "needs-restack"
	StatusMissingParent BranchStatus = "missing-parent"
)

type CreateOpts

type CreateOpts struct {
	Name string
	From string // optional start-point override
}

CreateOpts for Create.

type DeleteOpts

type DeleteOpts struct {
	Branch string
	Force  bool // git branch -D instead of -d
}

DeleteOpts for DeleteLocal.

type Engine

type Engine struct {
	Repo   *git.Repo
	Out    io.Writer // info messages (stderr-like); defaults to os.Stderr
	Quiet  bool      // suppress interactive rebase attach (use quiet rebase)
	NoPush bool      // ignored; push is per-call
	// contains filtered or unexported fields
}

Engine runs stack operations against a git repo.

func (*Engine) Adopt

func (e *Engine) Adopt(root string) error

Adopt writes local parent config from current resolution for branch and descendants.

func (*Engine) AncestorChainTo

func (e *Engine) AncestorChainTo(branch string) ([]string, error)

AncestorChainTo returns local stack chain from base (child of trunk) → branch, shallow first. Does not include trunk.

func (*Engine) BranchDepth

func (e *Engine) BranchDepth(branch string) int

BranchDepth is graph distance from trunk (0 = trunk), cycle-safe.

func (*Engine) BranchNeedsRestack

func (e *Engine) BranchNeedsRestack(branch, parent, parentRefOverride string) bool

BranchNeedsRestack reports whether branch is not based on parent tip.

func (*Engine) Create

func (e *Engine) Create(opts CreateOpts) error

Create makes a new branch from inferred or explicit parent.

func (*Engine) DeleteLocal

func (e *Engine) DeleteLocal(opts DeleteOpts) error

DeleteLocal deletes a local branch (-d or -D). Refuses trunk. If the branch is checked out, switches to its parent (or trunk) first. Clears local stack parent metadata for the deleted branch.

func (*Engine) DescendantsOf

func (e *Engine) DescendantsOf(root string) ([]string, error)

DescendantsOf returns local branches that have root as an ancestor in the parent graph (not name prefix).

func (*Engine) DivergePlaybook

func (e *Engine) DivergePlaybook(branch string) string

DivergePlaybook returns recovery help for a diverged branch (multiline).

func (*Engine) EnsureRemoteReady

func (e *Engine) EnsureRemoteReady(branch string) error

EnsureRemoteReady FFs if behind; returns error (with playbook) if diverged.

func (*Engine) FetchIfNeeded

func (e *Engine) FetchIfNeeded(noFetch bool) error

FetchIfNeeded fetches origin unless noFetch.

func (*Engine) InvalidateParentCache

func (e *Engine) InvalidateParentCache()

InvalidateParentCache drops in-memory and on-disk PR parent cache.

func (*Engine) IsTrunk

func (e *Engine) IsTrunk(name string) bool

IsTrunk reports whether name is the default branch.

func (*Engine) List

func (e *Engine) List(root string) ([]BranchInfo, error)

List returns stack tree info under root (or all stacks if root empty). When root is empty, trunk is first, then every branch in a stack graph (PR parent, local parent, dots, or ancestor of such).

func (*Engine) LoadParents

func (e *Engine) LoadParents(opts LoadParentsOpts) error

LoadParents populates the PR parent map (bulk gh pr list + disk cache).

func (*Engine) MaybePush

func (e *Engine) MaybePush(branch string, doPush bool) error

MaybePush pushes if doPush is true.

func (*Engine) PRStackBranches

func (e *Engine) PRStackBranches(branch string) []string

PRStackBranches returns the stack lineage for PR body display: trunk, ancestors of branch (shallow first), branch, then descendants (by depth). Used to render linked stack sections in PR descriptions.

func (*Engine) Parent

func (e *Engine) Parent(branch string) (string, error)

Parent prints inferred parent of branch (default: current).

func (*Engine) ParentOf

func (e *Engine) ParentOf(branch string) string

ParentOf resolves stack parent: PR base → local gitstack-parent config → dot-depth inference → trunk.

func (*Engine) ParentOfWithSource

func (e *Engine) ParentOfWithSource(branch string) (string, ParentSource)

ParentOfWithSource is ParentOf plus how it was resolved.

func (*Engine) Pull

func (e *Engine) Pull(branch string) error

Pull fetches origin and updates the local branch from origin/<branch>. Purely behind → fast-forward only; diverged → rebase onto origin. In-sync is a no-op; ahead errors (push instead).

func (*Engine) Reparent

func (e *Engine) Reparent(opts ReparentOpts) error

Reparent moves branch onto a different parent via rebase --onto.

func (*Engine) Restack

func (e *Engine) Restack(opts RestackOpts) error

Restack replays branch onto parent (or ancestor chain with OntoTrunk).

func (*Engine) RestackBranch

func (e *Engine) RestackBranch(branch, parent, parentRefOverride string) error

RestackBranch restacks local branch onto parent tip. parentRefOverride is optional (e.g. refs/remotes/origin/main for --onto-trunk).

func (*Engine) RestackUpstream

func (e *Engine) RestackUpstream(parentRef, branchRef string) (string, error)

RestackUpstream returns the cutoff SHA: only commits after this are replayed. Prefers fork-point so rewritten parents do not pull old parent commits.

func (*Engine) SetParentLocal

func (e *Engine) SetParentLocal(branch, parent string) error

SetParentLocal records an explicit parent in local config. If parent is trunk or empty, unsets the key. Rejects cycles.

func (*Engine) SlashRefConflict

func (e *Engine) SlashRefConflict(name string) (string, bool)

SlashRefConflict returns an existing ancestor path segment if name uses / under an existing branch (git forbids nesting).

func (*Engine) SortByDepth

func (e *Engine) SortByDepth(branches []string) []string

SortByDepth sorts branch names by graph depth ascending, then name.

func (*Engine) Sync

func (e *Engine) Sync(opts SyncOpts) (*SyncResult, error)

Sync plan-then-apply: FF, restack root, restack descendants.

func (*Engine) Track

func (e *Engine) Track(branch, parent string) error

Track sets local parent metadata without rebasing. Also retargets an open PR base when possible, because PR base wins over local config in ParentOf resolution (shared team source of truth).

func (*Engine) TrunkRef

func (e *Engine) TrunkRef() (string, error)

TrunkRef prefers origin/trunk, else local trunk.

func (*Engine) Untrack

func (e *Engine) Untrack(branch string) error

Untrack clears local parent metadata.

type LoadParentsOpts

type LoadParentsOpts struct {
	Offline bool // skip gh; use cache/local/dots only
	Refresh bool // force gh refresh even if cache is fresh
}

LoadParentsOpts controls bulk parent loading from GitHub.

type ParentSource

type ParentSource string

ParentSource explains how ParentOf resolved a parent.

const (
	SourceTrunk ParentSource = "trunk"
	SourcePR    ParentSource = "pr"
	SourceLocal ParentSource = "local"
	SourceDots  ParentSource = "name"
)

type PlanRow

type PlanRow struct {
	Branch string
	Remote git.RemoteRelation
	Action string
}

PlanRow is one line of a sync plan.

type ReparentOpts

type ReparentOpts struct {
	Branch    string
	NewParent string
	OldParent string // optional
	Push      bool
	NoFetch   bool
}

ReparentOpts for Reparent.

type RestackOpts

type RestackOpts struct {
	Branch    string
	Push      bool
	OntoTrunk bool
	NoFetch   bool
}

RestackOpts for Restack.

type SyncOpts

type SyncOpts struct {
	Root      string
	Push      bool
	OntoTrunk bool
	DryRun    bool
	NoFetch   bool
}

SyncOpts for Sync.

type SyncResult

type SyncResult struct {
	Plan     []PlanRow
	Blockers []string
}

SyncResult is the planned/applied sync outcome.