print error if unsupported flags are used

Docker 1.13 and up allows a client to communicate
with older daemons. As a result, flags may be
present that are not supported by the older daemon.

The client already _hides_ flags that are not
supported yet, but this doesn't present users
from using those flags.

This change shows an error if a flag is used
that is not supported by the daemon (either
based on the API version, or because experimental
features are not enabled).

Note that for some options, a check is already
in place in the API client. For those
options, this is just a minor enhancement
to more clearly indicate which _flag_ is
not supported.

Before this change;

    DOCKER_API_VERSION=1.24 docker run -d --stop-timeout=30 busybox top
    mjfyt3qpvnq0iwmun3sjwth9i

    echo -e "FROM busybox\nRUN echo foo > bar" |  DOCKER_API_VERSION=1.24 docker build --squash -
    "squash" requires API version 1.25, but the Docker server is version 1.24

After this change;

    DOCKER_API_VERSION=1.24 docker run -d --stop-timeout=30 busybox top
    "--stop-timeout" requires API version 1.25, but the Docker daemon is version 1.24

    echo -e "FROM busybox\nRUN echo foo > bar" | DOCKER_API_VERSION=1.24 docker build --squash -
    "--squash" requires API version 1.25, but the Docker daemon is version 1.24

    echo -e "FROM busybox\nRUN echo foo > bar" | docker build --squash -
    "--squash" is only supported on a Docker daemon with experimental features enabled

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

client/errors.go

@@ -229,7 +229,7 @@ func IsErrPluginPermissionDenied(err error) bool {
 // if less than the current supported version
 func (cli *Client) NewVersionError(APIrequired, feature string) error {
 	if versions.LessThan(cli.version, APIrequired) {
-		return fmt.Errorf("%q requires API version %s, but the Docker server is version %s", feature, APIrequired, cli.version)
+		return fmt.Errorf("%q requires API version %s, but the Docker daemon API version is %s", feature, APIrequired, cli.version)
 	}
 	return nil
 }

cmd/docker/docker.go

@@ -17,6 +17,7 @@ import (
 	"github.com/docker/docker/pkg/term"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
+	"strings"
 )
 
 func newDockerCommand(dockerCli *command.DockerCli) *cobra.Command {
@@ -144,7 +145,7 @@ func hideUnsupportedFeatures(cmd *cobra.Command, clientVersion string, hasExperi
 		}
 
 		// hide flags not supported by the server
-		if flagVersion, ok := f.Annotations["version"]; ok && len(flagVersion) == 1 && versions.LessThan(clientVersion, flagVersion[0]) {
+		if !isFlagSupported(f, clientVersion) {
 			f.Hidden = true
 		}
 
@@ -168,13 +169,44 @@ func hideUnsupportedFeatures(cmd *cobra.Command, clientVersion string, hasExperi
 func isSupported(cmd *cobra.Command, clientVersion string, hasExperimental bool) error {
 	if !hasExperimental {
 		if _, ok := cmd.Tags["experimental"]; ok {
-			return errors.New("only supported with experimental daemon")
+			return errors.New("only supported on a Docker daemon with experimental features enabled")
 		}
 	}
 
 	if cmdVersion, ok := cmd.Tags["version"]; ok && versions.LessThan(clientVersion, cmdVersion) {
-		return fmt.Errorf("only supported with daemon version >= %s", cmdVersion)
+		return fmt.Errorf("requires API version %s, but the Docker daemon API version is %s", cmdVersion, clientVersion)
+	}
+
+	errs := []string{}
+
+	cmd.Flags().VisitAll(func(f *pflag.Flag) {
+		if f.Changed {
+			if !isFlagSupported(f, clientVersion) {
+				errs = append(errs, fmt.Sprintf("\"--%s\" requires API version %s, but the Docker daemon API version is %s", f.Name, getFlagVersion(f), clientVersion))
+				return
+			}
+			if _, ok := f.Annotations["experimental"]; ok && !hasExperimental {
+				errs = append(errs, fmt.Sprintf("\"--%s\" is only supported on a Docker daemon with experimental features enabled", f.Name))
+			}
+		}
+	})
+	if len(errs) > 0 {
+		return errors.New(strings.Join(errs, "\n"))
 	}
 
 	return nil
 }
+
+func getFlagVersion(f *pflag.Flag) string {
+	if flagVersion, ok := f.Annotations["version"]; ok && len(flagVersion) == 1 {
+		return flagVersion[0]
+	}
+	return ""
+}
+
+func isFlagSupported(f *pflag.Flag, clientVersion string) bool {
+	if v := getFlagVersion(f); v != "" {
+		return versions.GreaterThanOrEqualTo(clientVersion, v)
+	}
+	return true
+}