cmd

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2026 License: MIT Imports: 47 Imported by: 0

Documentation

Overview

Package cmd implements the CLI commands for gz-git.

Index

Constants

View Source 
const WatchModeHelpText = `` /* 595-byte string literal not displayed */

WatchModeHelpText provides consistent documentation for watch mode across commands.

This constant centralizes watch mode documentation to ensure consistency across all commands that support the --watch flag (status, fetch, pull, push).

Variables

View Source 
var CoreFormats = cliutil.CoreFormats

CoreFormats contains formats supported by all commands.

View Source 
var ValidBulkFormats = cliutil.CoreFormats

ValidBulkFormats contains valid output formats for bulk operations Core formats + compact (bulk-specific).

View Source 
var ValidCloneStrategies = []string{"skip", "pull", "reset", "rebase", "fetch"}

ValidCloneStrategies contains valid strategy values for clone config.

View Source 
var ValidHistoryFormats = cliutil.TabularFormats

ValidHistoryFormats contains valid output formats for history commands Core formats + table, csv, markdown (history-specific).

Functions

func ApplyConfigToFlags 

func ApplyConfigToFlags(effective *config.EffectiveConfig, provider, baseURL, token *string, parallel *int)

ApplyConfigToFlags applies config values to command flags if not already set. This is useful for commands that want to use config as defaults.

Usage: 

effective, _ := LoadEffectiveConfig(cmd, nil)
if provider == "" && effective.Provider != "" {
    provider = effective.Provider
}

func Execute 

func Execute(version string)

Execute adds all child commands to the root command and sets flags appropriately. This is called by main.main(). It only needs to happen once to the rootCmd.

func FormatUpstreamFixHint 

func FormatUpstreamFixHint(branch, remote string) string

func IsValidCloneStrategy 

func IsValidCloneStrategy(strategy string) bool

IsValidCloneStrategy checks if the strategy is valid.

func LoadEffectiveConfig 

func LoadEffectiveConfig(cmd *cobra.Command, flags map[string]any) (*config.EffectiveConfig, error)

LoadEffectiveConfig loads configuration with precedence and merges with command flags. It handles profile override from --profile global flag.

Usage: 

effective, err := LoadEffectiveConfig(cmd, map[string]interface{}{
    "provider": provider,  // From command flags
    "org": org,
})

func PrintConfigSources 

func PrintConfigSources(cmd *cobra.Command, effective *config.EffectiveConfig)

PrintConfigSources prints the source of each config value (for debugging).

func RenderBulkResults 

func RenderBulkResults(w io.Writer, cfg BulkRenderConfig, in BulkRenderInput)

RenderBulkResults writes bulk operation results using the shared renderer.

func RunBulkWatch 

func RunBulkWatch(cfg WatchConfig, executor WatchExecutor) error

RunBulkWatch runs a bulk operation in watch mode with proper signal handling. This centralizes the watch loop logic used by fetch, pull, push, and status commands.

func WriteHealthSummaryLine 

func WriteHealthSummaryLine(w io.Writer, total int, summary reposync.HealthSummary, duration time.Duration)

WriteHealthSummaryLine prints a one-line health summary for diagnostic status. Example: "Status 6 repos [✓4 healthy ⚠1 warning ✗1 error] 1.2s".

func WriteSummaryLine 

func WriteSummaryLine(w io.Writer, verb string, total int, summary map[string]int, duration time.Duration)

WriteSummaryLine prints a one-line summary for bulk operations. Example: "Fetched 6 repos [=4 up-to-date ↓2 fetched] 1.2s".

Types

type BulkCommandFlags 

type BulkCommandFlags struct {
	Depth             int
	Parallel          int
	DryRun            bool
	IncludeSubmodules bool
	Include           string
	Exclude           string
	Format            string
	Watch             bool
	Interval          time.Duration
	SkipFetch         bool
}

BulkCommandFlags holds common flags for bulk operations (fetch, pull, push).

type BulkFlagOptions 

type BulkFlagOptions struct {
	SkipDryRun    bool
	SkipFetch     bool
	SkipFormat    bool
	SkipWatch     bool
	SkipRecursive bool
	SkipScanDepth bool
	SkipInclude   bool
	SkipExclude   bool
}

BulkFlagOptions allows customizing which bulk flags are registered.

type BulkRenderConfig 

type BulkRenderConfig struct {
	Title           string
	Verb            string
	Format          string
	Verbose         bool
	IssueStatuses   map[string]bool
	FormatStatus    func(row BulkRenderRow) string
	ChangesCount    func(row BulkRenderRow) int
	AlwaysShowError func(row BulkRenderRow) bool
	SuccessMessage  string
	// ShowFooters enables dirty-warning + auth-required footers (fetch/pull/push).
	ShowFooters bool
}

BulkRenderConfig configures command-specific rendering policy.

type BulkRenderInput 

type BulkRenderInput struct {
	TotalScanned, TotalProcessed int
	Duration                     time.Duration
	Summary                      map[string]int
	Rows                         []BulkRenderRow
}

BulkRenderInput is the aggregate bulk result view for rendering.

type BulkRenderRow 

type BulkRenderRow struct {
	Path, Branch, Status, Message, Remote string
	// Note is a command-specific detail the shared renderer never prints on its
	// own; a command surfaces it through its own FormatStatus. It exists because
	// Message reaches JSON output only, so a text-mode finding needs somewhere
	// to live that does not change what every other bulk command prints.
	Note                             string
	Err                              error
	Duration                         time.Duration
	CommitsAhead, CommitsBehind      int
	PushedCommits                    int
	UncommittedFiles, UntrackedFiles int
	Stashed, HasUncommittedChanges   bool
}

BulkRenderRow is the normalized per-repo view used by the shared bulk renderer.

type ChangedFileJSONOutput 

type ChangedFileJSONOutput struct {
	Path    string `json:"path"`
	Status  string `json:"status"`
	OldPath string `json:"old_path,omitempty"`
}

ChangedFileJSONOutput represents a changed file in JSON output.

type CleanJSONOutput 

type CleanJSONOutput struct {
	TotalScanned   int                         `json:"total_scanned"`
	TotalProcessed int                         `json:"total_processed"`
	TotalFiles     int                         `json:"total_files"`
	DurationMs     int64                       `json:"duration_ms"`
	Summary        map[string]int              `json:"summary"`
	Repositories   []CleanRepositoryJSONOutput `json:"repositories"`
}

CleanJSONOutput represents the JSON output structure for clean command.

type CleanRepositoryJSONOutput 

type CleanRepositoryJSONOutput struct {
	Path         string   `json:"path"`
	Branch       string   `json:"branch,omitempty"`
	Status       string   `json:"status"`
	FilesCount   int      `json:"files_count,omitempty"`
	FilesRemoved []string `json:"files_removed,omitempty"`
	DurationMs   int64    `json:"duration_ms,omitempty"`
	Error        string   `json:"error,omitempty"`
}

CleanRepositoryJSONOutput represents a single repository in JSON output.

type CloneConfig 

type CloneConfig struct {
	// Config metadata
	Version int             `yaml:"version,omitempty"` // Config version (1)
	Kind    CloneConfigKind `yaml:"kind,omitempty"`    // Config kind: groups, flat

	// Global settings (can be overridden by CLI flags or group settings)
	Parallel  int    `yaml:"parallel,omitempty"`
	Strategy  string `yaml:"strategy,omitempty"`  // skip, pull, reset, rebase, fetch
	Structure string `yaml:"structure,omitempty"` // flat or user

	// Flat format: single target + repositories list
	Target       string          `yaml:"target,omitempty"`
	Repositories []CloneRepoSpec `yaml:"repositories,omitempty"`

	// Grouped format: named groups (parsed separately due to dynamic keys)
	Groups map[string]*CloneGroup `yaml:"-"`
}

CloneConfig represents the YAML configuration for bulk clone. Supports two formats:

  1. Flat format: global settings + repositories array (kind: flat)
  2. Grouped format: global settings + named groups with their own targets (kind: groups)

type CloneConfigKind 

type CloneConfigKind string
const (
	// CloneKindGroups is the named groups format (recommended).
	CloneKindGroups CloneConfigKind = "groups"
	// CloneKindFlat is the flat repositories list format.
	CloneKindFlat CloneConfigKind = "flat"
)

func NormalizeCloneKind 

func NormalizeCloneKind(kind string) (CloneConfigKind, string, error)

NormalizeCloneKind normalizes kind value and returns canonical form.

type CloneGroup 

type CloneGroup struct {
	Target       string               `yaml:"target"`             // Required: target directory for this group
	Branch       configpkg.FlexBranch `yaml:"branch,omitempty"`   // Default branch for all repos in group
	Depth        int                  `yaml:"depth,omitempty"`    // Default depth for all repos in group
	Strategy     string               `yaml:"strategy,omitempty"` // Override global strategy
	Repositories []CloneRepoSpec      `yaml:"repositories"`       // Repository list
	Hooks        *CloneHooks          `yaml:"hooks,omitempty"`    // Group-level hooks (applied to all repos in group)
}

CloneGroup represents a named group of repositories with its own target.

type CloneHooks 

type CloneHooks struct {
	Before []string `yaml:"before,omitempty"` // Commands to run before clone/update
	After  []string `yaml:"after,omitempty"`  // Commands to run after clone/update
}

CloneHooks represents before/after hook commands for clone operations. Hooks are executed without shell interpretation for security (no pipes, redirects, etc.).

type CloneJSONOutput 

type CloneJSONOutput struct {
	TotalRequested int                       `json:"total_requested"`
	TotalCloned    int                       `json:"total_cloned"`
	TotalUpdated   int                       `json:"total_updated"`
	TotalSkipped   int                       `json:"total_skipped"`
	TotalFailed    int                       `json:"total_failed"`
	DurationMs     int64                     `json:"duration_ms"`
	Summary        map[string]int            `json:"summary"`
	Repositories   []CloneRepositoryJSONItem `json:"repositories"`
}

CloneJSONOutput represents the JSON output structure for clone command.

type CloneRepoSpec 

type CloneRepoSpec struct {
	URL    string               `yaml:"url"`              // Required
	Name   string               `yaml:"name,omitempty"`   // Optional: custom directory name (extracted from URL if empty)
	Path   string               `yaml:"path,omitempty"`   // Optional: subdirectory within target
	Branch configpkg.FlexBranch `yaml:"branch,omitempty"` // Optional: branch to checkout
	Depth  int                  `yaml:"depth,omitempty"`  // Optional: shallow clone depth
	Hooks  *CloneHooks          `yaml:"hooks,omitempty"`  // Optional: repo-level hooks
}

CloneRepoSpec represents a single repository specification in YAML.

type CloneRepositoryJSONItem 

type CloneRepositoryJSONItem struct {
	URL        string `json:"url"`
	Path       string `json:"path"`
	Status     string `json:"status"`
	Branch     string `json:"branch,omitempty"`
	DurationMs int64  `json:"duration_ms,omitempty"`
	Error      string `json:"error,omitempty"`
}

CloneRepositoryJSONItem represents a single repository in JSON output.

type CommitJSONOutput 

type CommitJSONOutput struct {
	TotalScanned    int                          `json:"total_scanned"`
	TotalDirty      int                          `json:"total_dirty"`
	TotalCommitted  int                          `json:"total_committed"`
	TotalSkipped    int                          `json:"total_skipped"`
	TotalConflicted int                          `json:"total_conflicted,omitempty"`
	TotalFailed     int                          `json:"total_failed"`
	DurationMs      int64                        `json:"duration_ms"`
	Summary         map[string]int               `json:"summary"`
	Repositories    []CommitRepositoryJSONOutput `json:"repositories"`
}

CommitJSONOutput represents the JSON output structure for commit command.

type CommitRepositoryJSONOutput 

type CommitRepositoryJSONOutput struct {
	Path                  string   `json:"path"`
	Branch                string   `json:"branch,omitempty"`
	Status                string   `json:"status"`
	CommitHash            string   `json:"commit_hash,omitempty"`
	Message               string   `json:"message,omitempty"`
	SuggestedMessage      string   `json:"suggested_message,omitempty"`
	FilesChanged          int      `json:"files_changed,omitempty"`
	TrackedFilesChanged   int      `json:"tracked_files_changed,omitempty"`
	UntrackedFilesChanged int      `json:"untracked_files_changed,omitempty"`
	StagedFilesChanged    int      `json:"staged_files_changed,omitempty"`
	Additions             int      `json:"additions,omitempty"`
	Deletions             int      `json:"deletions,omitempty"`
	ChangedFiles          []string `json:"changed_files,omitempty"`
	ConflictedFiles       []string `json:"conflicted_files,omitempty"`
	DurationMs            int64    `json:"duration_ms,omitempty"`
	Error                 string   `json:"error,omitempty"`
}

CommitRepositoryJSONOutput represents a single repository in JSON output.

type DiffJSONOutput 

type DiffJSONOutput struct {
	TotalScanned     int                        `json:"total_scanned"`
	TotalWithChanges int                        `json:"total_with_changes"`
	TotalClean       int                        `json:"total_clean"`
	DurationMs       int64                      `json:"duration_ms"`
	Summary          map[string]int             `json:"summary"`
	Repositories     []DiffRepositoryJSONOutput `json:"repositories"`
}

DiffJSONOutput represents the JSON output structure for diff command.

type DiffRepositoryJSONOutput 

type DiffRepositoryJSONOutput struct {
	Path                  string                  `json:"path"`
	Branch                string                  `json:"branch,omitempty"`
	Status                string                  `json:"status"`
	Scope                 string                  `json:"scope,omitempty"`
	FilesChanged          int                     `json:"files_changed,omitempty"`
	TrackedFilesChanged   int                     `json:"tracked_files_changed,omitempty"`
	UntrackedFilesChanged int                     `json:"untracked_files_changed,omitempty"`
	StagedFilesChanged    int                     `json:"staged_files_changed,omitempty"`
	Additions             int                     `json:"additions,omitempty"`
	Deletions             int                     `json:"deletions,omitempty"`
	DiffSummary           string                  `json:"diff_summary,omitempty"`
	DiffContent           string                  `json:"diff_content,omitempty"`
	ChangedFiles          []ChangedFileJSONOutput `json:"changed_files,omitempty"`
	UntrackedFiles        []string                `json:"untracked_files,omitempty"`
	OmittedFiles          []OmittedFileJSONOutput `json:"omitted_files,omitempty"`
	Truncated             bool                    `json:"truncated,omitempty"`
	DurationMs            int64                   `json:"duration_ms,omitempty"`
	Error                 string                  `json:"error,omitempty"`
}

DiffRepositoryJSONOutput represents a single repository in JSON output.

type InfoJSONOutput 

type InfoJSONOutput struct {
	TotalScanned   int                        `json:"total_scanned"`
	TotalProcessed int                        `json:"total_processed"`
	DurationMs     int64                      `json:"duration_ms"`
	Summary        map[string]int             `json:"summary"`
	Repositories   []InfoRepositoryJSONOutput `json:"repositories"`
}

InfoJSONOutput is the structured contract for `gz-git info`. Unlike status, it includes remote_only_branches: complete remote-tracking refs with no corresponding local, current, base, or upstream branch.

type InfoRepositoryJSONOutput 

type InfoRepositoryJSONOutput struct {
	Path               string   `json:"path"`
	Branch             string   `json:"branch,omitempty"`
	Status             string   `json:"status"`
	UncommittedFiles   int      `json:"uncommitted_files,omitempty"`
	UntrackedFiles     int      `json:"untracked_files,omitempty"`
	CommitsAhead       int      `json:"commits_ahead,omitempty"`
	CommitsBehind      int      `json:"commits_behind,omitempty"`
	ConflictFiles      []string `json:"conflict_files,omitempty"`
	RemoteOnlyBranches []string `json:"remote_only_branches"`
	DurationMs         int64    `json:"duration_ms,omitempty"`
	Error              string   `json:"error,omitempty"`
}

type OmittedFileJSONOutput 

type OmittedFileJSONOutput struct {
	Path   string `json:"path"`
	Reason string `json:"reason"`
}

OmittedFileJSONOutput reports an untracked file whose content was not included in the diff body, so consumers can tell a complete diff from a partial one instead of having to assume.

type StashJSONOutput 

type StashJSONOutput struct {
	Operation      string                      `json:"operation"`
	TotalScanned   int                         `json:"total_scanned"`
	TotalProcessed int                         `json:"total_processed"`
	TotalStashes   int                         `json:"total_stashes"`
	DurationMs     int64                       `json:"duration_ms"`
	Repositories   []StashRepositoryJSONOutput `json:"repositories"`
}

type StashRepositoryJSONOutput 

type StashRepositoryJSONOutput struct {
	Path    string `json:"path"`
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

type StatusJSONOutput 

type StatusJSONOutput struct {
	TotalScanned   int                          `json:"total_scanned"`
	TotalProcessed int                          `json:"total_processed"`
	DurationMs     int64                        `json:"duration_ms"`
	Summary        map[string]int               `json:"summary"`
	Repositories   []StatusRepositoryJSONOutput `json:"repositories"`
}

StatusJSONOutput represents the JSON output structure for status command.

type StatusRepositoryJSONOutput 

type StatusRepositoryJSONOutput struct {
	Path             string   `json:"path"`
	Branch           string   `json:"branch,omitempty"`
	Status           string   `json:"status"`
	UncommittedFiles int      `json:"uncommitted_files,omitempty"`
	UntrackedFiles   int      `json:"untracked_files,omitempty"`
	CommitsAhead     int      `json:"commits_ahead,omitempty"`
	CommitsBehind    int      `json:"commits_behind,omitempty"`
	ConflictFiles    []string `json:"conflict_files,omitempty"`
	DurationMs       int64    `json:"duration_ms,omitempty"`
	Error            string   `json:"error,omitempty"`
}

StatusRepositoryJSONOutput represents a single repository in JSON output.

type SwitchJSONOutput 

type SwitchJSONOutput struct {
	TargetBranch   string                       `json:"target_branch"`
	TotalScanned   int                          `json:"total_scanned"`
	TotalProcessed int                          `json:"total_processed"`
	DurationMs     int64                        `json:"duration_ms"`
	Summary        map[string]int               `json:"summary"`
	Repositories   []SwitchRepositoryJSONOutput `json:"repositories"`
}

SwitchJSONOutput represents the JSON output structure for switch command.

type SwitchRepositoryJSONOutput 

type SwitchRepositoryJSONOutput struct {
	Path           string `json:"path"`
	Status         string `json:"status"`
	PreviousBranch string `json:"previous_branch,omitempty"`
	CurrentBranch  string `json:"current_branch,omitempty"`
	Message        string `json:"message,omitempty"`
	DurationMs     int64  `json:"duration_ms,omitempty"`
}

SwitchRepositoryJSONOutput represents a single repository in JSON output.

type TagJSONOutput 

type TagJSONOutput struct {
	Operation      string                    `json:"operation"`
	TotalScanned   int                       `json:"total_scanned"`
	TotalProcessed int                       `json:"total_processed"`
	TotalTags      int                       `json:"total_tags"`
	DurationMs     int64                     `json:"duration_ms"`
	Repositories   []TagRepositoryJSONOutput `json:"repositories"`
}

TagJSONOutput represents the JSON output structure for tag command.

type TagRepositoryJSONOutput 

type TagRepositoryJSONOutput struct {
	Path    string `json:"path"`
	Status  string `json:"status"`
	Message string `json:"message,omitempty"`
}

TagRepositoryJSONOutput represents a single repository in JSON output.

type WatchConfig 

type WatchConfig struct {
	Interval      time.Duration
	Format        string
	Quiet         bool
	OperationName string // e.g., "fetch", "pull", "push", "status check"
	Directory     string
	MaxDepth      int
	Parallel      int
}

WatchConfig holds configuration for watch mode operations.

type WatchExecutor 

type WatchExecutor func() error

WatchExecutor is a function that executes the bulk operation once. Returns an error if the operation fails.

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.