flags

package
v1.21.1 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package flags manages command-line flags and environment variables for Watchtower configuration. It configures Docker connections, operational behavior, and notifications via Cobra and Viper.

Layout:

  • internal/flags/spec — FlagSpec metadata (static defaults, env keys, list parse kind)
  • internal/flags/<domain> — Specs() and/or Register per subsystem
  • internal/flags/utils — list parsers, env helpers, deprecation
  • RegisterAll / BindAll / AllSpecs — parent façade

Domain packages match the config taxonomy: docker, client, schedule, mode, update, lifecycle, filter, registry, compat, api, notify, logging.

Key components:

  • RegisterAll: Registers every domain's flags on the root command.
  • RegisterDockerFlags / RegisterSystemFlags / RegisterNotificationFlags: Domain-group helpers for tests.
  • BindAll: Applies Viper defaults, BindPFlag, and BindEnv from FlagSpec rows.
  • SetupLogging: Reconfigures a *zerolog.Logger (format writer + level) from flags and returns the updated logger.
  • ProcessFlagAliases / GetSecretsFromFiles: Pre-load transforms (porcelain, interval→schedule, secrets).
  • EnvConfig: Maps Docker client flags into DOCKER_* process environment variables.

Every domain exposes FlagSpec with static pflag defaults. BindAll and Load resolve values as flag > env > default. ApplyEnvToFlags bridges env onto unset flags for pre-load helpers without baking env into registration defaults.

Usage example: 

log := logging.New(os.Stderr, logging.InfoLevel)
cmd := &cobra.Command{}
flags.SetDefaults()
flags.RegisterAll(cmd)
log, err := flags.SetupLogging(log, cmd.PersistentFlags())
if err != nil {
    log.Fatal().Err(err).Msg("Logging setup failed")
}

Resolved process policy belongs in internal/config via config.Load. This package only declares and binds flags. It does not own update policy DTOs.

Logging helpers accept and return *zerolog.Logger explicitly (no global logger). Format/level configuration uses internal/logging (ConfigureWriter, ParseLevel).

Index

Constants

View Source 
const DockerAPIMinVersion string = "1.24"

DockerAPIMinVersion sets the minimum Docker API version supported by Watchtower.

Variables

View Source 
var (
	// ErrFlagNotRegistered indicates a FlagSpec name was not found on the flag set.
	ErrFlagNotRegistered = errors.New("flag not registered")
	// ErrInvalidFlagDefault indicates a FlagSpec default value has the wrong type.
	ErrInvalidFlagDefault = errors.New("invalid flag default")
	// ErrUnsupportedFlagKind indicates a FlagSpec kind is not supported.
	ErrUnsupportedFlagKind = errors.New("unsupported flag kind")
)

Functions

func AllSpecs 

func AllSpecs() []spec.FlagSpec

AllSpecs returns aggregated FlagSpec rows from every domain.

Returns:

  • []spec.FlagSpec: Flag metadata for BindAll.

func ApplyEnvToFlags 

func ApplyEnvToFlags(flagSet *pflag.FlagSet, specs []spec.FlagSpec) error

ApplyEnvToFlags copies bound environment values onto flags that were not set on the CLI.

Call after Cobra parse and before ProcessFlagAliases / SetupLogging so those helpers still see env-sourced values via flag Gets. Load continues to resolve through Viper with flag > env > default precedence. Static pflag defaults are never env-baked at registration time.

Parameters:

  • flagSet: Parsed persistent flag set.
  • specs: Aggregated FlagSpec rows.

Returns:

  • error: Non-nil when a flag cannot be set from env.

func BindAll 

func BindAll(vip *viper.Viper, flagSet *pflag.FlagSet, specs []spec.FlagSpec) error

BindAll applies Viper defaults, flag binds, and env binds from FlagSpec rows.

Call after Cobra has parsed flags. Static flag defaults come from Specs. env values participate through BindEnv without baking into pflag defaults.

Parameters:

  • vip: Local Viper instance for this process load.
  • flagSet: Parsed persistent flag set.
  • specs: Aggregated domain flag specifications.

Returns:

  • error: Non-nil when a bind or default application fails.

func CollectSpecs 

func CollectSpecs(groups ...[]spec.FlagSpec) []spec.FlagSpec

CollectSpecs aggregates FlagSpec rows from domain Specs functions.

Parameters:

  • groups: Domain Specs() results.

Returns:

  • []spec.FlagSpec: Combined specification list.

func EnvConfig 

func EnvConfig(log *zerolog.Logger, cmd *cobra.Command) error

EnvConfig sets Docker environment variables from flags.

Parameters:

  • log: Logger for configuration diagnostics.
  • cmd: Cobra command with flags.

Returns:

  • error: Non-nil if flag retrieval fails, nil on success.

func GetSecretsFromFiles 

func GetSecretsFromFiles(log *zerolog.Logger, rootCmd *cobra.Command)

GetSecretsFromFiles updates flags with file contents for secrets.

Parameters:

  • log: Logger for secret-loading diagnostics and fatal failures.
  • rootCmd: Root Cobra command.

func IsPresenceEnvKey 

func IsPresenceEnvKey(envKey string) bool

IsPresenceEnvKey reports whether envKey uses presence-means-true semantics.

func ProcessFlagAliases 

func ProcessFlagAliases(log *zerolog.Logger, flags *pflag.FlagSet)

ProcessFlagAliases applies environment values then syncs flag aliases.

It bridges env onto unset flags, then applies porcelain mode, interval versus schedule conflicts, and debug/trace log-level forcing.

Intended production order (see cmd preRun / notify-upgrade):

  1. ApplyEnvToFlags (or rely on the bridge inside this function)
  2. SetupLogging — apply --log-format (and current level) so Fatal paths here use the user-selected format rather than zerolog's default JSON encoding
  3. ProcessFlagAliases — may force log-level to debug/trace and may Fatal
  4. SetupLogging again — re-apply level after alias mutations
  5. GetSecretsFromFiles / EnvConfig / config.Load

Call after Cobra parse. Do not call only after a single post-alias SetupLogging if format-before-fatal matters. Sandwich this between the two SetupLogging calls.

Parameters:

  • log: Logger for alias diagnostics and fatal configuration errors.
  • flags: Parsed persistent flag set.

func RegisterAll 

func RegisterAll(rootCmd *cobra.Command)

RegisterAll registers every domain's flags on the root command.

Domain packages match the config taxonomy: docker, client, schedule, mode, update, lifecycle, filter, registry, compat, api, notify, logging.

Parameters:

  • rootCmd: Root Cobra command.

func RegisterDockerFlags 

func RegisterDockerFlags(rootCmd *cobra.Command)

RegisterDockerFlags adds Docker API client flags to the root command.

Prefer RegisterAll when registering the full flag set.

Parameters:

  • rootCmd: Root Cobra command.

func RegisterNotificationFlags 

func RegisterNotificationFlags(rootCmd *cobra.Command)

RegisterNotificationFlags adds notification flags to the root command.

Prefer RegisterAll when registering the full flag set.

Parameters:

  • rootCmd: Root Cobra command.

func RegisterSystemFlags 

func RegisterSystemFlags(rootCmd *cobra.Command)

RegisterSystemFlags registers non-Docker, non-notification domain flags.

Prefer RegisterAll. Kept for tests that call domain groups separately.

Parameters:

  • rootCmd: Root Cobra command.

func SetDefaults 

func SetDefaults()

SetDefaults enables automatic environment lookup on the global Viper instance.

Flag static defaults and process Load bind live on FlagSpec rows. This remains for tests and helpers that still touch the global Viper (for example EnvDuration).

func SetupLogging 

func SetupLogging(log *zerolog.Logger, flags *pflag.FlagSet) (*zerolog.Logger, error)

SetupLogging configures format and level on the provided logger.

Parameters:

  • log: Logger to reconfigure (typically from logging.New at process start).
  • flags: Flag set.

Returns:

  • *zerolog.Logger: Logger with format writer and level applied.
  • error: Non-nil if config fails, nil on success.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
Package api registers HTTP API transport and endpoint flags.
 Package api registers HTTP API transport and endpoint flags.
Package client registers Docker client construction flags.
 Package client registers Docker client construction flags.
Package compat registers runtime compatibility flags.
 Package compat registers runtime compatibility flags.
Package docker registers Docker API client flags.
 Package docker registers Docker API client flags.
Package filter registers container selection flags.
 Package filter registers container selection flags.
Package lifecycle registers pre/post update lifecycle hook flags.
 Package lifecycle registers pre/post update lifecycle hook flags.
Package logging registers console logging flags.
 Package logging registers console logging flags.
Package mode registers process entry-shape flags.
 Package mode registers process entry-shape flags.
Package notify registers notification-related CLI and environment flags.
 Package notify registers notification-related CLI and environment flags.
Package registry registers registry TLS flags.
 Package registry registers registry TLS flags.
Package schedule registers poll interval and cron schedule flags.
 Package schedule registers poll interval and cron schedule flags.
Package spec defines shared flag metadata used by domain registration and Viper bind.
 Package spec defines shared flag metadata used by domain registration and Viper bind.
Package update registers container update policy flags.
 Package update registers container update policy flags.
Package utils provides shared helpers for flag registration and value parsing.
 Package utils provides shared helpers for flag registration and value parsing.

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.