cmdutils

package
v1.100.0 Latest Latest
Warning

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

 Go to latest Published: May 27, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Overview

This file implements URL parsing for GitLab resources to allow commands to accept full GitLab URLs instead of just resource IDs.

TODO: Unify this URL parsing logic with issueutils.issueMetadataFromURL in a follow-up MR to avoid code duplication and ensure consistency.

Supported URL formats: - Merge Requests: https://gitlab.com/group/project/-/merge_requests/123 - Issues: https://gitlab.com/group/project/-/issues/456 - Self-managed instances: https://invent.kde.org/kde/project/-/merge_requests/42 - Deep subgroups: https://gitlab.com/group/sub1/sub2/project/-/merge_requests/123 - URL fragments and query parameters are automatically stripped

Index

Constants

View Source 
const (
	IssueTemplate        = "issue_templates"
	MergeRequestTemplate = "merge_request_templates"
)

Variables

View Source 
var GroupMemberLevel = map[int]string{
	0:  "no access",
	5:  "minimal access",
	10: "guest",
	20: "reporter",
	30: "developer",
	40: "maintainer",
	50: "owner",
}

GroupMemberLevel maps a number representing the access level to a string shown to the user. API docs: https://docs.gitlab.com/ce/api/members.html#valid-access-levels

View Source 
var PipelineInputsDescription string
View Source 
var (
	// SilentError is an error that triggers exit Code 1 without any error messaging
	SilentError = errors.New("SilentError")
)

Functions

func AddGlobalRepoOverride 

func AddGlobalRepoOverride(cmd *cobra.Command, f Factory)

AddGlobalRepoOverride adds the -R flag globally but keeps it hidden

func AddJQFlag added in v1.100.0 

func AddJQFlag(cmd *cobra.Command, io *iostreams.IOStreams)

AddJQFlag registers the --jq flag on a command that emits JSON via IOStreams.PrintJSON. The flag's value is parsed (and the resulting jq query compiled) by cobra at parse time, via the IOStreams.JQFilter pflag.Value attached to io.JQ.

In PreRun, the helper verifies that the command's output flag (looked up by name: --output first, then --output-format) is set to "json". Commands without either output flag (e.g. orbit/*) always emit JSON and skip this check. The verification fails the command before RunE runs, so non-JSON output is never produced when --jq is active.

func AddPipelineInputsFlag added in v1.73.0 

func AddPipelineInputsFlag(cmd *cobra.Command)

AddPipelineInputsFlag adds a flag to a cobra command for pipeline inputs.

func CancelError 

func CancelError(log ...any) error

func EditorPrompt 

func EditorPrompt(ctx context.Context, io *iostreams.IOStreams, response *string, question, templateContent, editorCommand string) error

func EnableJSONOutput added in v1.89.0 

func EnableJSONOutput(cmd *cobra.Command, io *iostreams.IOStreams, outputFormat *string, customDescription ...string)

EnableJSONOutput adds the --output/-F flag to a command for JSON output support, and also registers --jq via AddJQFlag so callers do not have to invoke both helpers.

By default it uses a standard description. Pass a custom description to override.

func EnableRepoOverride 

func EnableRepoOverride(cmd *cobra.Command, f Factory)

func GetEditor 

func GetEditor(cf func() config.Config) (string, error)

func GitLabErrorHandler added in v1.73.1 

func GitLabErrorHandler(w io.Writer, styles fang.Styles, err error)

GitLabErrorHandler is a custom error handler for fang that handles GitLab CLI specific errors

func GroupOverride 

func GroupOverride(cmd *cobra.Command) (string, error)

func HandleDescriptionEditor added in v1.88.0 

func HandleDescriptionEditor(ctx context.Context, description *string, io *iostreams.IOStreams, cfg func() config.Config, templateSelector TemplateSelectionFunc) error

HandleDescriptionEditor handles the -d- flag by optionally showing template selection and then opening an external editor with the template contents. If templateSelector is nil, no template selection is shown (empty editor).

func IDsFromUsers 

func IDsFromUsers(users []*gitlab.User) *[]int64

IDsFromUsers collects all user IDs from a slice of users

func LabelsPrompt 

func LabelsPrompt(ctx context.Context, ios *iostreams.IOStreams, response *[]string, apiClient *gitlab.Client, repoRemote *glrepo.Remote) error

func ListGitLabTemplates 

func ListGitLabTemplates(tmplType string) ([]string, error)

TODO: properly handle errors in this function. 

For now, it returns nil and empty slice if there's an error

func LoadGitLabTemplate 

func LoadGitLabTemplate(tmplType, tmplName string) (string, error)

LoadGitLabTemplate finds and loads the GitLab template from the working git directory Follows the format officially supported by GitLab https://docs.gitlab.com/user/project/description_templates/#set-a-default-template-for-merge-requests-and-issues.

TODO: load from remote repository if repo is overridden by -R flag

func MilestonesPrompt 

func MilestonesPrompt(ctx context.Context, response *int64, apiClient *gitlab.Client, repoRemote *glrepo.Remote, ios *iostreams.IOStreams) error

func MinimumArgs 

func MinimumArgs(n int, msg string) cobra.PositionalArgs

func NewBoolFlagPair added in v1.87.0 

func NewBoolFlagPair(cmd *cobra.Command, v **bool, onName, onDesc, offName, offDesc string)

NewBoolFlagPair sets up two mutually exclusive boolean flags that can be mapped to the same underlying value. For example a `--pause` and `--unpause`, where `--pause` sets the underlying value to `true` and `--unpause` to false. Not setting either of the flags results the underlying to be `nil`.

func NewEnumValue added in v1.64.0 

func NewEnumValue[T ~string](allowed []T, d T, v *T) *enumValue[T]

func ParseMergeRequestFromURL added in v1.68.0 

func ParseMergeRequestFromURL(urlStr, defaultHostname string) (int, glrepo.Interface)

ParseMergeRequestFromURL extracts merge request ID and repository from a GitLab URL Returns 0 and nil if the URL is not a valid merge request URL

func ParseMilestone 

func ParseMilestone(apiClient *gitlab.Client, repo glrepo.Interface, milestoneTitle string) (int64, error)

func PipelineInputsFromFlags added in v1.73.0 

func PipelineInputsFromFlags(cmd *cobra.Command) (gitlab.PipelineInputsOption, error)

PipelineInputsFromFlags creates a gitlab.PipelineInputsOption from the "input" command line flag.

Returns a nil map if the flag is not set.

func UsersPrompt 

func UsersPrompt(ctx context.Context, response *[]string, apiClient *gitlab.Client, repoRemote *glrepo.Remote, io *iostreams.IOStreams, minimumAccessLevel int, role string) error

UsersPrompt creates a multi-selection prompt of all the users above the given access level for the remote referenced by the `*glrepo.Remote`.

`role` will appear on the prompt to keep the user informed of the reason of the selection.

Types

type Action 

type Action int
const (
	NoAction Action = iota
	SubmitAction
	PreviewAction
	AddMetadataAction
	CancelAction
	EditCommitMessageAction
)
const (
	AddLabelAction Action = iota
	AddAssigneeAction
	AddMilestoneAction
)

func ConfirmSubmission 

func ConfirmSubmission(ctx context.Context, ios *iostreams.IOStreams, allowAddMetadata bool) (Action, error)

func PickMetadata 

func PickMetadata(ctx context.Context, io *iostreams.IOStreams) ([]Action, error)

type AllowedValuer added in v1.92.0 

type AllowedValuer interface {
	AllowedValues() []string
}

AllowedValuer can be implemented by flag.Value types that have a constrained set of valid values, so callers (e.g. MCP schema generation) can surface them.

type DefaultFactory 

type DefaultFactory struct {
	// contains filtered or unexported fields
}

func NewFactory 

func NewFactory(io *iostreams.IOStreams, resolveRepos bool, cfg config.Config, buildInfo api.BuildInfo) *DefaultFactory

func (*DefaultFactory) ApiClient 

func (f *DefaultFactory) ApiClient(repoHost string) (*api.Client, error)

func (*DefaultFactory) BaseRepo 

func (f *DefaultFactory) BaseRepo() (glrepo.Interface, error)

func (*DefaultFactory) Branch 

func (f *DefaultFactory) Branch() (string, error)

func (*DefaultFactory) BuildInfo 

func (f *DefaultFactory) BuildInfo() api.BuildInfo

func (*DefaultFactory) Config 

func (f *DefaultFactory) Config() config.Config

func (*DefaultFactory) DefaultHostname 

func (f *DefaultFactory) DefaultHostname() string

func (*DefaultFactory) Executor added in v1.81.0 

func (f *DefaultFactory) Executor() Executor

func (*DefaultFactory) GitLabClient added in v1.66.0 

func (f *DefaultFactory) GitLabClient() (*gitlab.Client, error)

func (*DefaultFactory) GitRunner added in v1.94.0 

func (f *DefaultFactory) GitRunner() git.GitRunner

func (*DefaultFactory) IO 

func (f *DefaultFactory) IO() *iostreams.IOStreams

func (*DefaultFactory) Remotes 

func (f *DefaultFactory) Remotes() (glrepo.Remotes, error)

func (*DefaultFactory) RepoOverride 

func (f *DefaultFactory) RepoOverride(repo string) error

type Executor added in v1.81.0 

type Executor interface {
	// LookPath searches for an executable named file in the
	// directories named by the PATH environment variable.
	//
	// In production code forwards to exec.LookPath.
	LookPath(file string) (string, error)
	// Exec executes the given binary with args and env and sets up IO.
	//
	// In production code it sets up IO with the configured iostreams.
	Exec(ctx context.Context, name string, args []string, env []string) error
	// Exec executes the given binary with args and env and returns the combined stdout and stderr output.
	ExecWithCombinedOutput(ctx context.Context, name string, args []string, env []string) ([]byte, error)
	// Exec executes the given binary with args and env and configures the IOs with the given arguments.
	ExecWithIO(ctx context.Context, name string, args []string, env []string, stdin io.Reader, stdout, stderr io.Writer) error
}

type ExitError 

type ExitError struct {
	Err     error
	Code    int
	Details string
}

func WrapError 

func WrapError(err error, log string) *ExitError

func WrapErrorWithCode 

func WrapErrorWithCode(err error, code int, details string) *ExitError

func (*ExitError) Error 

func (e *ExitError) Error() string

func (ExitError) Unwrap 

func (e ExitError) Unwrap() error

type Factory 

type Factory interface {
	RepoOverride(repo string) error
	ApiClient(repoHost string) (*api.Client, error)
	// GitLabClient returns an HTTP client that is initialize with the host from BaseRepo.
	// You must only use GitLabClient if your command is tied to a single repository,
	// otherwise use ApiClient
	GitLabClient() (*gitlab.Client, error)
	BaseRepo() (glrepo.Interface, error)
	Remotes() (glrepo.Remotes, error)
	Config() config.Config
	Branch() (string, error)
	IO() *iostreams.IOStreams
	DefaultHostname() string
	BuildInfo() api.BuildInfo
	Executor() Executor
	GitRunner() git.GitRunner
}

Factory is a way to obtain core tools for the commands. Safe for concurrent use.

type FlagError 

type FlagError struct {
	Err error
}

FlagError is the kind of error raised in flag processing

func (FlagError) Error 

func (fe FlagError) Error() string

func (FlagError) Unwrap 

func (fe FlagError) Unwrap() error

type GetTextUsingEditor 

type GetTextUsingEditor func(ctx context.Context, editor, tmpFileName, content string) (string, error)

type GitLabResourceMetadata added in v1.68.0 

type GitLabResourceMetadata struct {
	ID   int
	Type GitLabResourceType
	Repo glrepo.Interface
}

GitLabResourceMetadata contains the parsed metadata from a GitLab URL

func ParseGitLabURL added in v1.68.0 

func ParseGitLabURL(urlStr, defaultHostname string) *GitLabResourceMetadata

type GitLabResourceType added in v1.68.0 

type GitLabResourceType string

GitLabResourceType represents the type of GitLab resource 

const (
	// GitLabResourceMergeRequest represents a merge request resource
	GitLabResourceMergeRequest GitLabResourceType = "merge_request"

	// GitLabResourceIssue represents an issue resource
	GitLabResourceIssue GitLabResourceType = "issue"
)

type TemplateSelectionFunc added in v1.88.0 

type TemplateSelectionFunc func(ctx context.Context) (string, error)

TemplateSelectionFunc is a callback function that returns template contents. It allows each command to customize its template selection logic.

type UserAssignmentType 

type UserAssignmentType int
const (
	AssigneeAssignment UserAssignmentType = iota
	ReviewerAssignment
)

type UserAssignments 

type UserAssignments struct {
	ToAdd          []string
	ToRemove       []string
	ToReplace      []string
	AssignmentType UserAssignmentType
}

UserAssignments holds 3 slice strings that represent which assignees should be added, removed, and replaced helper functions are also provided

func ParseAssignees 

func ParseAssignees(assignees []string) *UserAssignments

ParseAssignees takes a String Slice and splits them into 3 Slice Strings based on the first character of a string.

'+' is put in the first slice, '!' and '-' in the second slice and all other cases in the third slice.

The 3 String slices are returned regardless if anything was put it in or not the user is responsible for checking the length to see if anything is in it

func (*UserAssignments) UsersFromAddRemove 

func (ua *UserAssignments) UsersFromAddRemove(
	issueAssignees []*gitlab.IssueAssignee,
	mergeRequestAssignees []*gitlab.BasicUser,
	apiClient *gitlab.Client,
	actions []string,
) (*[]int64, []string, error)

UsersFromAddRemove works with both `ToAdd` and `ToRemove` members to produce a Slice of Ints that represents the final collection of IDs to assigned.

It starts by getting all IDs already assigned, but ignoring ones present in `ToRemove`, it then converts all `usernames` in `ToAdd` into IDs by using the `api` package and adds them to the IDs to be assigned

func (*UserAssignments) UsersFromReplaces 

func (ua *UserAssignments) UsersFromReplaces(apiClient *gitlab.Client, actions []string) (*[]int64, []string, error)

UsersFromReplaces converts all users from the `ToReplace` member of the struct into an Slice of String representing the Users' IDs, it also takes a Slice of Strings and writes a proper action message to it

func (*UserAssignments) VerifyAssignees 

func (ua *UserAssignments) VerifyAssignees() error

VerifyAssignees is a method for UserAssignments that checks them for validity

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.