Documentation
¶
Overview ¶
Package common provides shared helper functions for CLI commands.
Package common provides shared helper functions for CLI commands.
Index ¶
- Constants
- func ApplyReadOnlyCurrentBranch(opts app.GlobalOptions) app.GlobalOptions
- func Checkout(ctx *app.Context, opts actions.CheckoutOptions, ...) (actions.CheckoutResult, error)
- func CommandPhase(cmd *cobra.Command, phase PhasePrefix) string
- 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
- func RunCommandHooks(ctx *app.Context, cmd *cobra.Command, phase PhasePrefix) error
- func RunReadOnlyCurrentBranch(cmd *cobra.Command, fn func(ctx *app.Context) error) error
- func RunWithOptions(cmd *cobra.Command, opts app.GlobalOptions, fn func(ctx *app.Context) error) error
- type BaseHandler
- type BranchResult
- type BranchResultStatus
- type ExitCodeError
- type PhasePrefix
Constants ¶
const ( ReasonNoRestackNeeded = "does not need restacking" ReasonLocked = "is locked" ReasonFrozen = "is frozen" )
Restack reason constants used by sync and get handlers.
Variables ¶
This section is empty.
Functions ¶
func ApplyReadOnlyCurrentBranch ¶ added in v0.18.0
func ApplyReadOnlyCurrentBranch(opts app.GlobalOptions) app.GlobalOptions
ApplyReadOnlyCurrentBranch tunes opts for commands that only inspect the current branch or its parent chain: skip the full metadata bootstrap and the managed-worktree check. Compose this when the optimization only applies to some code paths (e.g. show vs. write modes of a single command).
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 CommandPhase ¶ added in v0.19.0
func CommandPhase(cmd *cobra.Command, phase PhasePrefix) string
CommandPhase returns the lookup key under hooks: in .stackit.yaml for the given cobra command and phase, e.g. "pre-modify" or "post-worktree-create".
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 ¶
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 ¶
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 ¶
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 ¶
ResolveBranchArg returns the first positional branch argument, or the current branch name when no argument was provided.
func RunCommandHooks ¶ added in v0.19.0
RunCommandHooks fires the configured hooks for the given lifecycle phase.
Zero-cost when absent: the only work performed when no hook is configured for this command + phase is a slice-length check against the in-memory project config that was already loaded during context construction.
Returns the hook's error verbatim for pre-hooks (so the caller can abort the command). For post-hooks, errors are surfaced as warnings on ctx.Output and nil is returned.
func RunReadOnlyCurrentBranch ¶ added in v0.18.0
RunReadOnlyCurrentBranch is for commands whose every code path is a read-only inspection of the current branch or its parent chain.
func RunWithOptions ¶ added in v0.18.0
func RunWithOptions(cmd *cobra.Command, opts app.GlobalOptions, fn func(ctx *app.Context) error) error
RunWithOptions is like Run but allows commands to tune context construction.
Types ¶
type BaseHandler ¶
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).
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 )
type ExitCodeError ¶ added in v0.18.0
type ExitCodeError struct {
// contains filtered or unexported fields
}
ExitCodeError wraps an error from a child process with the exit code stackit should return to its caller.
func NewExitCodeError ¶ added in v0.18.0
func NewExitCodeError(code int, err error) *ExitCodeError
func (*ExitCodeError) Error ¶ added in v0.18.0
func (e *ExitCodeError) Error() string
func (*ExitCodeError) ExitCode ¶ added in v0.18.0
func (e *ExitCodeError) ExitCode() int
func (*ExitCodeError) Unwrap ¶ added in v0.18.0
func (e *ExitCodeError) Unwrap() error
type PhasePrefix ¶ added in v0.19.0
type PhasePrefix string
PhasePrefix identifies whether a hook fires before or after the command.
const ( PhasePre PhasePrefix = "pre" PhasePost PhasePrefix = "post" )
Source Files