Clarify definition of --pull options

Fixes: containers#5406

Signed-off-by: Daniel J Walsh <[email protected]>

cmd/buildah/from.go

@@ -70,7 +70,12 @@ func init() {
  flags.StringVar(&opts.creds, "creds", "", "use `[username[:password]]` for accessing the registry")
  flags.StringVarP(&opts.format, "format", "f", defaultFormat(), "`format` of the image manifest and metadata")
  flags.StringVar(&opts.name, "name", "", "`name` for the working container")
- flags.StringVar(&opts.pull, "pull", "true", "pull images from the registry if newer or not present in store, if false, only pull images if not present, if always, pull images even if the named images are present in store, if never, only use images present in store if available")
+ flags.StringVar(&opts.pull, "pull", "true", `pull images from the registry values:
+true: pull if newer or not present in store,
+false: never pull images even if not present,
+always: pull images even if the named images are present in store,
+missing: pull images if the named images are not present in store,
+never: only use images present in store if available`)
  flags.Lookup("pull").NoOptDefVal = "true" //allow `--pull ` to be set to `true` as expected.
 
  flags.BoolVar(&opts.pullAlways, "pull-always", false, "pull the image even if the named image is present in store")

docs/buildah-build.1.md

@@ -751,7 +751,7 @@ any listed registry and is not present locally.
 
 If the flag is disabled (with *--pull=false*), do not pull base and SBOM
 scanner images from registries, use only local versions. Raise an error if a
-base or SBOM scanner image is not present locally.
+base or SBOM scanner image is not present locally. Equivalent to *--pull=never*.
 
 If the pull flag is set to `always` (with *--pull=always*), pull base and SBOM
 scanner images from the registries listed in registries.conf. Raise an error
@@ -764,7 +764,7 @@ storage. Raise an error if no image could be found and the pull fails.
 
 If the pull flag is set to `never` (with *--pull=never*), do not pull base and
 SBOM scanner images from registries, use only the local versions. Raise an
-error if the image is not present locally.
+error if the image is not present locally. Equivalent to *--pull=false*.
 
 Defaults to *true*.
 

docs/buildah-from.1.md

@@ -379,15 +379,15 @@ registry and is not present locally.
 
 If the flag is disabled (with *--pull=false*), do not pull the image from the
 registry, use only the local version. Raise an error if the image is not
-present locally.
+present locally. Equivalent to *--pull=never*.
 
 If the pull flag is set to `always` (with *--pull=always*),
 pull the image from the first registry it is found in as listed in registries.conf.
 Raise an error if not found in the registries, even if the image is present locally.
 
 If the pull flag is set to `never` (with *--pull=never*),
 Do not pull the image from the registry, use only the local version. Raise an error
-if the image is not present locally.
+if the image is not present locally. Equivalent to *--pull=false*.
 
 Defaults to *true*.
 

pkg/cli/common.go

@@ -262,7 +262,12 @@ func GetBudFlags(flags *BudResults) pflag.FlagSet {
  fs.String("os", runtime.GOOS, "set the OS to the provided value instead of the current operating system of the host")
  fs.StringArrayVar(&flags.OSFeatures, "os-feature", []string{}, "set required OS `feature` for the target image in addition to values from the base image")
  fs.StringVar(&flags.OSVersion, "os-version", "", "set required OS `version` for the target image instead of the value from the base image")
- fs.StringVar(&flags.Pull, "pull", "true", "pull base and SBOM scanner images from the registry if newer or not present in store, if false, only pull base and SBOM scanner images if not present, if always, pull base and SBOM scanner images even if the named images are present in store, if never, only use images present in store if available")
+ fs.StringVar(&flags.Pull, "pull", "true", `pull base and SBOM scanner images from the registry. Values:
+true: pull if newer or not present in store.
+false: never pull base and SBOM scanner images.
+always: pull base and SBOM scanner images even if the named images are present in store.
+missing: pull base and SBOM scanner images if the named images are not present in store.
+never: only use images present in store if available`)
  fs.Lookup("pull").NoOptDefVal = "true" //allow `--pull ` to be set to `true` as expected.
  fs.BoolVar(&flags.PullAlways, "pull-always", false, "pull the image even if the named image is present in store")
  if err := fs.MarkHidden("pull-always"); err != nil {