Merge pull request #14870 from vrothberg/fix-14846

improve pull-policy documentation

cmd/podman/common/completion.go

@@ -966,7 +966,7 @@ func AutocompleteLogOpt(cmd *cobra.Command, args []string, toComplete string) ([
 // AutocompletePullOption - Autocomplete pull options for create and run command.
 // -> "always", "missing", "never"
 func AutocompletePullOption(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-	pullOptions := []string{"always", "missing", "never"}
+	pullOptions := []string{"always", "missing", "never", "newer"}
 	return pullOptions, cobra.ShellCompDirectiveNoFileComp
 }
 

cmd/podman/common/create.go

@@ -390,7 +390,7 @@ func DefineCreateFlags(cmd *cobra.Command, cf *entities.ContainerCreateOptions,
 		createFlags.StringVar(
 			&cf.Pull,
 			pullFlagName, cf.Pull,
-			`Pull image before creating ("always"|"missing"|"never")`,
+			`Pull image policy`,
 		)
 		_ = cmd.RegisterFlagCompletionFunc(pullFlagName, AutocompletePullOption)
 

docs/source/markdown/podman-build.1.md

@@ -576,27 +576,14 @@ While `podman build` is happy to use base images and build images for any
 platform that exists, `RUN` instructions will not be able to succeed without
 the help of emulation provided by packages like `qemu-user-static`.
 
-#### **--pull**
+#### **--pull**=**always**|**missing**|**never**|**newer**
 
-When the option is enabled or set explicitly to `true` (with *--pull=true*)
+Pull image policy. The default is **always**.
-pull the image from the first registry it is found in as listed in registries.conf.
-Raise an error if the image could not be pulled, even if the image is present locally.
 
-If the option is disabled (with *--pull=false*), pull the image from the
+- **always**, **true**: Always pull the image and throw an error if the pull fails.
-registry only if the image is not present locally. Raise an error if the image is not
+- **missing**: Pull the image only if it could not be found in the local containers storage.  Throw an error if no image could be found and the pull fails.
-in the registries and not present locally.
+- **never**, **false**: Never pull the image but use the one from the local containers storage.  Throw an error if no image could be found.
-
+- **newer**: Pull if the image on the registry is newer than the one in the local containers storage.  An image is considered to be newer when the digests are different.  Comparing the time stamps is prone to errors.  Pull errors are suppressed if a local image was found.
-If the pull option 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 option is set to `missing` (with *--pull=missing*),
-Pull the image only if it is not present in the local storage.  Raise an error if it
-could neither be found in the local storage or on a registry.
-
-If the pull option 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.
 
 #### **--quiet**, **-q**
 

docs/source/markdown/podman-create.1.md

@@ -866,14 +866,14 @@ port to a random port on the host within an *ephemeral port range* defined by
 `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host
 ports and the exposed ports, use `podman port`.
 
-#### **--pull**=*missing*
+#### **--pull**=**always**|**missing**|**never**|**newer**
 
-Pull image before creating ("always"|"missing"|"never") (default "missing").
+Pull image policy. The default is **missing**.
-       'missing': default value, attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist.Raise an error if the image is not in any listed registry and is not present locally.
-       '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.
-       'never': do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally.
 
-Defaults to *missing*.
+- **always**: Always pull the image and throw an error if the pull fails.
+- **missing**: Pull the image only if it could not be found in the local containers storage.  Throw an error if no image could be found and the pull fails.
+- **never**: Never pull the image but use the one from the local containers storage.  Throw an error if no image could be found.
+- **newer**: Pull if the image on the registry is newer than the one in the local containers storage.  An image is considered to be newer when the digests are different.  Comparing the time stamps is prone to errors.  Pull errors are suppressed if a local image was found.
 
 #### **--quiet**, **-q**
 

docs/source/markdown/podman-run.1.md

@@ -905,13 +905,14 @@ When using this option, Podman will bind any exposed port to a random port on th
 within an ephemeral port range defined by */proc/sys/net/ipv4/ip_local_port_range*.
 To find the mapping between the host ports and the exposed ports, use **podman port**.
 
-#### **--pull**=**always**|**missing**|**never**
+#### **--pull**=**always**|**missing**|**never**|**newer**
 
-Pull image before running. The default is **missing**.
+Pull image policy. The default is **missing**.
 
-- **missing**: attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist.Raise an error if the image is not in any listed registry and is not present locally.
+- **always**: Always pull the image and throw an error if the pull fails.
-- **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.
+- **missing**: Pull the image only if it could not be found in the local containers storage.  Throw an error if no image could be found and the pull fails.
-- **never**: do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally.
+- **never**: Never pull the image but use the one from the local containers storage.  Throw an error if no image could be found.
+- **newer**: Pull if the image on the registry is newer than the one in the local containers storage.  An image is considered to be newer when the digests are different.  Comparing the time stamps is prone to errors.  Pull errors are suppressed if a local image was found.
 
 #### **--quiet**, **-q**