ux: improve the usage doc of --image-spec (#1334)

Signed-off-by: Xiaoxuan Wang <wangxiaoxuan119@gmail.com>

cmd/oras/internal/option/spec.go

@@ -27,7 +27,6 @@ import (
 const (
 	ImageSpecV1_1 = "v1.1"
 	ImageSpecV1_0 = "v1.0"
-	ImageSpecAuto = "auto"
 )
 
 const (
@@ -45,7 +44,7 @@ type ImageSpec struct {
 func (is *ImageSpec) Set(value string) error {
 	is.Flag = value
 	switch value {
-	case ImageSpecV1_1, ImageSpecAuto:
+	case ImageSpecV1_1:
 		is.PackVersion = oras.PackManifestVersion1_1
 	case ImageSpecV1_0:
 		is.PackVersion = oras.PackManifestVersion1_0
@@ -68,21 +67,21 @@ func (is *ImageSpec) Options() string {
 	return strings.Join([]string{
 		ImageSpecV1_1,
 		ImageSpecV1_0,
-		ImageSpecAuto,
 	}, ", ")
 }
 
 // String returns the string representation of the flag.
 func (is *ImageSpec) String() string {
-	return is.Flag
+	// to avoid printing default value in usage doc
+	return ""
 }
 
 // ApplyFlags applies flags to a command flag set.
 func (is *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
-	// default to auto
+	// default to v1.1, unless --config is used and --artifact-type is not used
 	is.PackVersion = oras.PackManifestVersion1_1
-	is.Flag = ImageSpecAuto
-	fs.Var(is, "image-spec", fmt.Sprintf(`[Experimental] specify manifest type for building artifact. Options: %s (default %q)`, is.Options(), ImageSpecAuto))
+	is.Flag = ImageSpecV1_1
+	fs.Var(is, "image-spec", `[Experimental] specify manifest type for building artifact. Options: v1.1, v1.0 (default v1.1, overridden to v1.0 if --config is used without --artifact-type)`)
 }
 
 // DistributionSpec option struct which implements pflag.Value interface.

cmd/oras/root/push.go

@@ -110,13 +110,13 @@ Example - Push file "hi.txt" into an OCI image layout folder 'layout-dir' with t
 			}
 
 			if opts.manifestConfigRef != "" && opts.artifactType == "" {
-				switch opts.Flag {
-				case option.ImageSpecAuto:
-					// switch to v1.0 manifest since artifact type is suggested by OCI v1.1
-					// artifact guidance but is not presented
+				if !cmd.Flags().Changed("image-spec") {
+					// switch to v1.0 manifest since artifact type is suggested
+					// by OCI v1.1 artifact guidance but is not presented
 					// see https://github.com/opencontainers/image-spec/blob/e7f7c0ca69b21688c3cea7c87a04e4503e6099e2/manifest.md?plain=1#L170
+					opts.Flag = option.ImageSpecV1_0
 					opts.PackVersion = oras.PackManifestVersion1_0
-				case option.ImageSpecV1_1:
+				} else if opts.Flag == option.ImageSpecV1_1 {
 					return &oerrors.Error{
 						Err:            errors.New(`missing artifact type for OCI image-spec v1.1 artifacts`),
 						Recommendation: "set an artifact type via `--artifact-type` or consider image spec v1.0",