common

Documentation

Overview

Package common provides shared helper functions for CLI commands.

Package common provides shared helper functions for CLI commands.

Index

• Constants
• func Checkout(ctx *app.Context, opts actions.CheckoutOptions, ...) (actions.CheckoutResult, error)
• func CompleteBranches(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective)
• func CompleteCheckout(ctx *app.Context, result actions.CheckoutResult, ...) error
• func FormatBranchSummary(out output.Output, results []BranchResult) (success, fail int)
• func FormatPRInfo(prNumber *int) string
• func GetGlobalOptions(cmd *cobra.Command) app.GlobalOptions
• func HandleCheckoutResult(out output.Output, result actions.CheckoutResult) bool
• func HandleCommandError(err error) error
• func HasShellIntegration() bool
• func ReadMessage(message, messageFile string) (string, error)
• func ResolveBranchArg(ctx *app.Context, args []string, missingErr error) (string, error)
• func Run(cmd *cobra.Command, fn func(ctx *app.Context) error) error
• type BaseHandler
  • func NewBaseHandler(out output.Output) BaseHandler
  • func (h *BaseHandler) Cleanup()
  • func (h *BaseHandler) IsInteractive() bool
  • func (h *BaseHandler) Lock()
  • func (h *BaseHandler) Unlock()
• type BranchResult
• type BranchResultStatus

Constants

const (
	ReasonNoRestackNeeded = "does not need restacking"
	ReasonLocked          = "is locked"
	ReasonFrozen          = "is frozen"
)

Restack reason constants used by sync and get handlers.

Functions

func Checkout

func Checkout(ctx *app.Context, opts actions.CheckoutOptions, handler actions.CheckoutHandler) (actions.CheckoutResult, error)

Checkout runs CheckoutAction and completes any worktree-switch fallback.

func CompleteBranches

func CompleteBranches(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective)

CompleteBranches is a helper for cobra.ValidArgsFunction and RegisterFlagCompletionFunc that returns all branch names in the repository.

func CompleteCheckout

func CompleteCheckout(ctx *app.Context, result actions.CheckoutResult, fallbackOpts actions.CheckoutOptions, handler actions.CheckoutHandler) error

CompleteCheckout handles a CheckoutAction result, including the fallback checkout path when shell integration cannot switch worktrees for the caller.

func FormatBranchSummary

func FormatBranchSummary(out output.Output, results []BranchResult) (success, fail int)

FormatBranchSummary formats a list of branch results for display. Returns the count of successful and failed operations.

func FormatPRInfo

func FormatPRInfo(prNumber *int) string

FormatPRInfo formats a PR number for display. Returns empty string if prNumber is nil.

func GetGlobalOptions

func GetGlobalOptions(cmd *cobra.Command) app.GlobalOptions

GetGlobalOptions returns runtime.GlobalOptions populated from a cobra.Command's flags

func HandleCheckoutResult

func HandleCheckoutResult(out output.Output, result actions.CheckoutResult) bool

HandleCheckoutResult handles the worktree switch result from CheckoutAction. Returns true if shell integration handled the switch (caller should return nil). Returns false with tips printed if no shell integration.

func HandleCommandError

func HandleCommandError(err error) error

HandleCommandError formats known error types for user display.

func HasShellIntegration

func HasShellIntegration() bool

HasShellIntegration checks if stackit shell integration is installed. The shell wrapper sets STACKIT_SHELL_INTEGRATION=1 when running commands.

func ReadMessage

func ReadMessage(message, messageFile string) (string, error)

ReadMessage resolves a commit message from either an inline -m string or a --message-file path. Used by create/modify/squash/split to keep variable commit-message text out of the literal command line, which keeps Claude permission rules stable across distinct messages and avoids shell-escaping pitfalls for multi-line subject+body messages.

If messageFile is "-", reads from stdin. If both flags are set, returns an error. Trims surrounding whitespace; preserves internal newlines so multi-line bodies survive intact. Errors when the resolved message is empty (file is empty or stdin received nothing) — the caller passed --message-file expecting a message, so silent fallthrough to other input paths would mask the mistake.

func ResolveBranchArg

func ResolveBranchArg(ctx *app.Context, args []string, missingErr error) (string, error)

ResolveBranchArg returns the first positional branch argument, or the current branch name when no argument was provided.

func Run

func Run(cmd *cobra.Command, fn func(ctx *app.Context) error) error

Run is a helper that provides a runtime context to a command's execution function

Types

type BaseHandler

type BaseHandler struct {
	Output output.Output
	// contains filtered or unexported fields
}

BaseHandler provides common functionality for CLI handlers. Embed this in handler structs to reduce boilerplate.

func NewBaseHandler

func NewBaseHandler(out output.Output) BaseHandler

NewBaseHandler creates a new BaseHandler with the given output.

func (*BaseHandler) Cleanup

func (h *BaseHandler) Cleanup()

Cleanup is a default no-op implementation.

func (*BaseHandler) IsInteractive

func (h *BaseHandler) IsInteractive() bool

IsInteractive returns false by default (for simple handlers).

func (*BaseHandler) Lock

func (h *BaseHandler) Lock()

Lock acquires the handler's mutex.

func (*BaseHandler) Unlock

func (h *BaseHandler) Unlock()

Unlock releases the handler's mutex.

type BranchResult

type BranchResult struct {
	BranchName string
	Status     BranchResultStatus
	Output     string
	Error      error
	IsCurrent  bool
}

BranchResult holds data for formatting branch operation results.

type BranchResultStatus

type BranchResultStatus int

BranchResultStatus represents the status of a branch operation.

const (
	// StatusDone indicates the operation completed successfully.
	StatusDone BranchResultStatus = iota
	// StatusError indicates the operation failed.
	StatusError
)