stack

package
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

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.

func PRLabel added in v0.1.8 

func PRLabel(n int) string

PRLabel formats a PR number for display ("#123" or "—").

Types

type BranchInfo 

type BranchInfo struct {
	Name       string
	Parent     string
	ShortSHA   string
	OwnCommits string
	Status     BranchStatus
	Depth      int
	Remote     git.RemoteRelation
	// PRNumber is the open PR for this branch head, or 0 if none/unknown.
	PRNumber int
	// 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.

Each branch name appears at most once. If infos contains duplicates (same Name), the entry with the higher PRNumber wins; ties keep the later entry. Parent/children edges are also de-duplicated.

type BranchStatus 

type BranchStatus string

BranchStatus is status for ls / TUI. 

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

type ConflictMode added in v0.1.6 

type ConflictMode int

ConflictMode controls rebase failure handling. 

const (
	// ConflictRollback aborts a failed rebase and leaves the worktree clean.
	ConflictRollback ConflictMode = iota
	// ConflictResolve leaves the rebase in progress so conflicts can be fixed.
	ConflictResolve
)

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

	// ConflictMode is rollback (default) or resolve. See ConflictMode.
	ConflictMode ConflictMode
	// contains filtered or unexported fields
}

Engine runs stack operations against a git repo.

func (*Engine) AbortOnConflict added in v0.1.6 

func (e *Engine) AbortOnConflict() bool

AbortOnConflict is true when failed rebases should be aborted (rollback mode).

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) PRNumber added in v0.1.8 

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

PRNumber returns the open PR number for branch, or 0 if unknown.

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 runs `git pull` on branch (checks it out first if needed). Uses the branch's configured upstream and the user's pull.* settings — same as running git pull in the terminal. No custom ff/rebase logic.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.