gh

Documentation

Overview

Package gh wraps the GitHub CLI for stacked PR create/retarget.

Index

• Constants
• func Available() bool
• func CachePath(gitDir string) string
• func EnsurePR(repo *git.Repo, opts PROpts) (string, error)
• func FormatStackMarkdown(prs map[string]PRInfo, branches []string, current string) string
• func HasPR(repo *git.Repo, branch string) bool
• func InvalidatePRParentCache(gitDir string)
• func LoadPRParentCache(gitDir string, maxAge time.Duration) (map[string]string, bool)
• func OpenPRWeb(repo *git.Repo, branch string) error
• func RetargetBase(repo *git.Repo, branch, newBase string) error
• func SavePRCache(gitDir string, infos map[string]PRInfo) error
• func SavePRParentCache(gitDir string, parents map[string]string) error
• func UpsertStackSection(body, inner string) string
• type Client
  • func (c *Client) ListOpenPRParents() (map[string]string, error)
  • func (c *Client) ListOpenPRs() (map[string]PRInfo, error)
• type PRCache
  • func LoadPRCache(gitDir string, maxAge time.Duration) (PRCache, bool)
• type PRInfo
• type PROpts

Constants

const (
	StackSectionStart = "<!-- git-stack -->"
	StackSectionEnd   = "<!-- /git-stack -->"
)

Markers for the auto-managed stack section in a PR body. Edit freely above/below; content between markers is rewritten on create/update.

const CacheTTL = 5 * time.Minute

CacheTTL is how long the on-disk PR parent cache is considered fresh.

Functions

func Available

func Available() bool

Available reports whether gh is on PATH.

func CachePath

func CachePath(gitDir string) string

CachePath returns .git/git-stack/pr-parents.json for a git dir.

func EnsurePR

func EnsurePR(repo *git.Repo, opts PROpts) (string, error)

EnsurePR creates or retargets a PR with the given base. When StackBranches is set, upserts a stack section (with markers) at the top of the PR body.

func FormatStackMarkdown

func FormatStackMarkdown(prs map[string]PRInfo, branches []string, current string) string

FormatStackMarkdown builds the inner stack section (no markers) for a branch list. branches should be ordered base → tip (typically trunk first). current is marked.

func HasPR

func HasPR(repo *git.Repo, branch string) bool

HasPR reports whether an open (or any) PR exists for the branch head.

func InvalidatePRParentCache

func InvalidatePRParentCache(gitDir string)

InvalidatePRParentCache removes the cache file.

func LoadPRParentCache

func LoadPRParentCache(gitDir string, maxAge time.Duration) (map[string]string, bool)

LoadPRParentCache reads parents only (compat helper).

func OpenPRWeb

func OpenPRWeb(repo *git.Repo, branch string) error

OpenPRWeb opens the PR for branch in the default browser via gh.

func RetargetBase

func RetargetBase(repo *git.Repo, branch, newBase string) error

RetargetBase sets PR base if a PR exists for branch. Returns nil if gh is missing or no PR exists.

func SavePRCache

func SavePRCache(gitDir string, infos map[string]PRInfo) error

SavePRCache writes full open-PR snapshot under .git/git-stack/.

func SavePRParentCache

func SavePRParentCache(gitDir string, parents map[string]string) error

SavePRParentCache writes parents only, preserving numbers/urls when present.

func UpsertStackSection

func UpsertStackSection(body, inner string) string

UpsertStackSection puts stack markdown between markers at the top of the body. If markers already exist, only the section between them is replaced. Otherwise the section is prepended.

Types

type Client

type Client struct {
	Dir string
}

Client shells out to gh.

func (*Client) ListOpenPRParents

func (c *Client) ListOpenPRParents() (map[string]string, error)

ListOpenPRParents returns headRefName → baseRefName for open PRs (one gh call).

func (*Client) ListOpenPRs

func (c *Client) ListOpenPRs() (map[string]PRInfo, error)

ListOpenPRs returns open PRs keyed by head branch name.

type PRCache

type PRCache struct {
	Parents map[string]string
	Numbers map[string]int
	URLs    map[string]string
}

PRCache is the on-disk / in-memory open-PR snapshot.

func LoadPRCache

func LoadPRCache(gitDir string, maxAge time.Duration) (PRCache, bool)

LoadPRCache reads the on-disk PR cache. ok is false if missing/stale/invalid.

type PRInfo

type PRInfo struct {
	Head   string
	Base   string
	Number int
	URL    string
	Draft  bool
}

PRInfo is a minimal open PR used for stack parent resolution.

type PROpts

type PROpts struct {
	Branch string
	Base   string // required stack parent (caller resolves)
	Draft  bool
	// StackBranches is the stack ordered base → tip (e.g. trunk, …, branch, …kids).
	// When non-empty, a linked stack section is written at the top of the PR body.
	StackBranches []string
}

PROpts for create/retarget.