refactor: mark --verbose as deprecated (#1558)

Signed-off-by: Lixia (Sylvia) Lei <[email protected]>

cmd/oras/root/attach.go

@@ -44,7 +44,8 @@ type attachOptions struct {
 
 	artifactType string
 	concurrency  int
-	verbose      bool
+	// Deprecated: verbose is deprecated and will be removed in the future.
+	verbose bool
 }
 
 func attachCmd() *cobra.Command {
@@ -117,9 +118,10 @@ Example - Attach file to the manifest tagged 'v1' in an OCI image layout folder
 
 	cmd.Flags().StringVarP(&opts.artifactType, "artifact-type", "", "", "artifact type")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 5, "concurrency level")
-	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "print status output for unnamed blobs")
+	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", true, "print status output for unnamed blobs")
 	opts.FlagDescription = "[Preview] attach to an arch-specific subject"
 	_ = cmd.MarkFlagRequired("artifact-type")
+	_ = cmd.Flags().MarkDeprecated("verbose", "and will be removed in a future release.")
 	opts.EnableDistributionSpecFlag()
 	opts.SetTypes(option.FormatTypeText, option.FormatTypeJSON, option.FormatTypeGoTemplate)
 	option.ApplyFlags(&opts, cmd.Flags())

cmd/oras/root/blob/push.go

@@ -42,7 +42,8 @@ type pushBlobOptions struct {
 	fileRef   string
 	mediaType string
 	size      int64
-	verbose   bool
+	// Deprecated: verbose is deprecated and will be removed in the future.
+	verbose bool
 }
 
 func pushCmd() *cobra.Command {
@@ -98,7 +99,8 @@ Example - Push blob 'hi.txt' into an OCI image layout folder 'layout-dir':
 
 	cmd.Flags().Int64VarP(&opts.size, "size", "", -1, "provide the blob size")
 	cmd.Flags().StringVarP(&opts.mediaType, "media-type", "", ocispec.MediaTypeImageLayer, "specify the returned media type in the descriptor if --descriptor is used")
-	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "print status output for unnamed blobs")
+	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", true, "print status output for unnamed blobs")
+	_ = cmd.Flags().MarkDeprecated("verbose", "and will be removed in a future release.")
 	option.ApplyFlags(&opts, cmd.Flags())
 	return oerrors.Command(cmd, &opts.Target)
 }

cmd/oras/root/cp.go

@@ -50,7 +50,8 @@ type copyOptions struct {
 	recursive   bool
 	concurrency int
 	extraRefs   []string
-	verbose     bool
+	// Deprecated: verbose is deprecated and will be removed in the future.
+	verbose bool
 }
 
 func copyCmd() *cobra.Command {
@@ -104,7 +105,8 @@ Example - Copy an artifact with multiple tags with concurrency tuned:
 	}
 	cmd.Flags().BoolVarP(&opts.recursive, "recursive", "r", false, "[Preview] recursively copy the artifact and its referrer artifacts")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 3, "concurrency level")
-	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "print status output for unnamed blobs")
+	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", true, "print status output for unnamed blobs")
+	_ = cmd.Flags().MarkDeprecated("verbose", "and will be removed in a future release.")
 	opts.EnableDistributionSpecFlag()
 	option.ApplyFlags(&opts, cmd.Flags())
 	return oerrors.Command(cmd, &opts.BinaryTarget)

cmd/oras/root/manifest/push.go

@@ -48,7 +48,8 @@ type pushOptions struct {
 	extraRefs   []string
 	fileRef     string
 	mediaType   string
-	verbose     bool
+	// Deprecated: verbose is deprecated and will be removed in the future.
+	verbose bool
 }
 
 func pushCmd() *cobra.Command {
@@ -109,7 +110,8 @@ Example - Push a manifest to an OCI image layout folder 'layout-dir' and tag wit
 	option.ApplyFlags(&opts, cmd.Flags())
 	cmd.Flags().StringVarP(&opts.mediaType, "media-type", "", "", "media type of manifest")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 5, "concurrency level")
-	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "print status output for unnamed blobs")
+	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", true, "print status output for unnamed blobs")
+	_ = cmd.Flags().MarkDeprecated("verbose", "and will be removed in a future release.")
 	return oerrors.Command(cmd, &opts.Target)
 }
 

cmd/oras/root/pull.go

@@ -52,7 +52,8 @@ type pullOptions struct {
 	PathTraversal     bool
 	Output            string
 	ManifestConfigRef string
-	verbose           bool
+	// Deprecated: verbose is deprecated and will be removed in the future.
+	verbose bool
 }
 
 func pullCmd() *cobra.Command {
@@ -113,7 +114,8 @@ Example - Pull artifact files from an OCI layout archive 'layout.tar':
 	cmd.Flags().StringVarP(&opts.Output, "output", "o", ".", "output directory")
 	cmd.Flags().StringVarP(&opts.ManifestConfigRef, "config", "", "", "output manifest config file")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 3, "concurrency level")
-	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "print status output for unnamed blobs")
+	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", true, "print status output for unnamed blobs")
+	_ = cmd.Flags().MarkDeprecated("verbose", "and will be removed in a future release.")
 	opts.SetTypes(option.FormatTypeText, option.FormatTypeJSON, option.FormatTypeGoTemplate)
 	option.ApplyFlags(&opts, cmd.Flags())
 	return oerrors.Command(cmd, &opts.Target)

cmd/oras/root/push.go

@@ -52,7 +52,8 @@ type pushOptions struct {
 	manifestConfigRef string
 	artifactType      string
 	concurrency       int
-	verbose           bool
+	// Deprecated: verbose is deprecated and will be removed in the future.
+	verbose bool
 }
 
 func pushCmd() *cobra.Command {
@@ -165,7 +166,8 @@ Example - Push file "hi.txt" into an OCI image layout folder 'layout-dir' with t
 	cmd.Flags().StringVarP(&opts.manifestConfigRef, "config", "", "", "`path` of image config file")
 	cmd.Flags().StringVarP(&opts.artifactType, "artifact-type", "", "", "artifact type")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 5, "concurrency level")
-	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", false, "print status output for unnamed blobs")
+	cmd.Flags().BoolVarP(&opts.verbose, "verbose", "v", true, "print status output for unnamed blobs")
+	_ = cmd.Flags().MarkDeprecated("verbose", "and will be removed in a future release.")
 	opts.SetTypes(option.FormatTypeText, option.FormatTypeJSON, option.FormatTypeGoTemplate)
 	option.ApplyFlags(&opts, cmd.Flags())
 	return oerrors.Command(cmd, &opts.Target)

test/e2e/internal/testdata/feature/feature.go

@@ -15,6 +15,8 @@ limitations under the License.
 
 package feature
 
+const DeprecationMessageVerboseFlag = "Flag --verbose has been deprecated, and will be removed in a future release."
+
 var (
 	Preview = struct {
 		Mark        string

test/e2e/internal/utils/match/status.go

@@ -77,6 +77,11 @@ func newStateMachine(cmd string) *stateMachine {
 		sm.addPath("Skipped")
 		sm.addPath("Exists")
 		sm.addPath("Mounted")
+	case "manifest", "blob": // for `manifest push` and `blob push`
+		// TODO: refactor the matcher to match full command like `manifest push`, `manifest delete`, etc.
+		// Tracking issue: https://github.com/oras-project/oras/issues/1571
+		sm.addPath("Uploading", "Uploaded")
+		sm.addPath("Exists")
 	default:
 		ginkgo.Fail("Unrecognized cmd name " + cmd)
 	}

test/e2e/suite/auth/auth.go

@@ -179,7 +179,7 @@ var _ = Describe("Common registry user", func() {
 			src := RegistryRef(ZOTHost, ArtifactRepo, foobar.Tag)
 			dst := RegistryRef(ZOTHost, fmt.Sprintf("command/auth/%d/copy", GinkgoRandomSeed()), foobar.Tag)
 			foobarStates := append(foobar.ImageLayerStateKeys, foobar.ManifestStateKey, foobar.ImageConfigStateKey(oras.MediaTypeUnknownConfig))
-			ORAS("cp", src, dst, "-v", "--from-registry-config", LegacyConfigPath, "--to-registry-config", LegacyConfigPath).MatchStatus(foobarStates, true, len(foobarStates)).Exec()
+			ORAS("cp", src, dst, "--from-registry-config", LegacyConfigPath, "--to-registry-config", LegacyConfigPath).MatchStatus(foobarStates, true, len(foobarStates)).Exec()
 		})
 	})
 })

test/e2e/suite/command/attach.go

@@ -41,10 +41,41 @@ var _ = Describe("ORAS beginners:", func() {
 		RunAndShowPreviewInHelp([]string{"attach"})
 
 		It("should show preview and help doc", func() {
-			out := ORAS("attach", "--help").MatchKeyWords(feature.Preview.Mark+" Attach", feature.Preview.Description, ExampleDesc).Exec()
+			out := ORAS("attach", "--help").MatchKeyWords(feature.Preview.Mark+" Attach", feature.Preview.Description, ExampleDesc).Exec().Out
 			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
+		It("should not show --verbose in help doc", func() {
+			out := ORAS("push", "--help").MatchKeyWords(ExampleDesc).Exec().Out
+			gomega.Expect(out).ShouldNot(gbytes.Say("--verbose"))
+		})
+
+		It("should show deprecation message and print unnamed status output for --verbose", func() {
+			testRepo := attachTestRepo("test-verbose")
+			CopyZOTRepo(ImageRepo, testRepo)
+			subjectRef := RegistryRef(ZOTHost, testRepo, foobar.Tag)
+			stateKeys := []match.StateKey{
+				foobar.AttachFileStateKey,
+				{Digest: "44136fa355b3", Name: "application/vnd.oci.empty.v1+json"},
+			}
+			ORAS("attach", "--artifact-type", "test/attach", "--verbose", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				WithWorkDir(PrepareTempFiles()).
+				MatchErrKeyWords(feature.DeprecationMessageVerboseFlag).
+				MatchStatus(stateKeys, true, len(stateKeys)).Exec()
+		})
+
+		It("should show deprecation message and should NOT print unnamed status output for --verbose=false", func() {
+			testRepo := attachTestRepo("test-verbose-false")
+			CopyZOTRepo(ImageRepo, testRepo)
+			subjectRef := RegistryRef(ZOTHost, testRepo, foobar.Tag)
+			stateKeys := []match.StateKey{foobar.AttachFileStateKey}
+			out := ORAS("attach", "--artifact-type", "test/attach", "--verbose=false", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				WithWorkDir(PrepareTempFiles()).
+				MatchErrKeyWords(feature.DeprecationMessageVerboseFlag).
+				MatchStatus(stateKeys, false, len(stateKeys)).Exec().Out
+			gomega.Expect(out).ShouldNot(gbytes.Say("application/vnd.oci.empty.v1+json"))
+		})
+
 		It("should show text as default format type in help doc", func() {
 			MatchDefaultFlagValue("format", "text", "attach")
 		})

test/e2e/suite/command/blob.go

@@ -24,8 +24,10 @@ import (
 	. "github.com/onsi/ginkgo/v2"
 	"github.com/onsi/gomega"
 	"github.com/onsi/gomega/gbytes"
+	"oras.land/oras/test/e2e/internal/testdata/feature"
 	"oras.land/oras/test/e2e/internal/testdata/foobar"
 	. "oras.land/oras/test/e2e/internal/utils"
+	"oras.land/oras/test/e2e/internal/utils/match"
 )
 
 const (
@@ -39,6 +41,30 @@ var _ = Describe("ORAS beginners:", func() {
 	repoFmt := fmt.Sprintf("command/blob/%%s/%d/%%s", GinkgoRandomSeed())
 	When("running blob command", func() {
 		When("running `blob push`", func() {
+			It("should not show --verbose in help doc", func() {
+				out := ORAS("push", "--help").MatchKeyWords(ExampleDesc).Exec().Out
+				gomega.Expect(out).ShouldNot(gbytes.Say("--verbose"))
+			})
+
+			It("should show deprecation message and print unnamed status output for --verbose", func() {
+				repo := fmt.Sprintf(repoFmt, "push", "test-verbose")
+				ORAS("blob", "push", RegistryRef(ZOTHost, repo, pushDigest), "-", "--size", strconv.Itoa(len(pushContent)), "--verbose").
+					WithInput(strings.NewReader(pushContent)).
+					MatchErrKeyWords(feature.DeprecationMessageVerboseFlag).
+					MatchStatus([]match.StateKey{{Digest: "e1ca41574914", Name: "application/vnd.oci.image.layer.v1.tar"}}, true, 1).
+					Exec()
+			})
+
+			It("should show deprecation message and should NOT print unnamed status output for --verbose=false", func() {
+				repo := fmt.Sprintf(repoFmt, "push", "test-verbose-false")
+				out := ORAS("blob", "push", RegistryRef(ZOTHost, repo, pushDigest), "-", "--size", strconv.Itoa(len(pushContent)), "--verbose=false").
+					WithInput(strings.NewReader(pushContent)).
+					MatchErrKeyWords(feature.DeprecationMessageVerboseFlag).
+					Exec().Out
+				// should not print status output for unnamed blobs
+				gomega.Expect(out).ShouldNot(gbytes.Say("application/vnd.oci.image.layer.v1.tar"))
+			})
+
 			It("should fail to read blob content and password from stdin at the same time", func() {
 				repo := fmt.Sprintf(repoFmt, "push", "password-stdin")
 				ORAS("blob", "push", RegistryRef(ZOTHost, repo, ""), "--password-stdin", "-").
@@ -236,9 +262,11 @@ var _ = Describe("1.1 registry users:", func() {
 				MatchContent(fmt.Sprintf(pushDescFmt, mediaType)).Exec()
 			ORAS("blob", "fetch", RegistryRef(ZOTHost, repo, pushDigest), "--output", "-").MatchContent(pushContent).Exec()
 
-			ORAS("blob", "push", RegistryRef(ZOTHost, repo, ""), blobPath, "-v").
+			ORAS("blob", "push", RegistryRef(ZOTHost, repo, ""), blobPath).
 				WithDescription("skip the pushing if the blob already exists in the target repo").
-				MatchKeyWords("Exists").Exec()
+				MatchStatus([]match.StateKey{{Digest: "e1ca41574914", Name: "application/vnd.oci.image.layer.v1.tar"}}, true, 1).
+				MatchKeyWords("Exists").
+				Exec()
 		})
 
 		It("should push a blob from a stdin and output the descriptor with specific media-type", func() {
@@ -347,7 +375,7 @@ var _ = Describe("OCI image layout users:", func() {
 			// test
 			ORAS("blob", "push", Flags.Layout, LayoutRef(tmpRoot, pushDigest), blobPath, "--media-type", mediaType, "--descriptor").
 				MatchContent(fmt.Sprintf(pushDescFmt, mediaType)).Exec()
-			ORAS("blob", "push", Flags.Layout, LayoutRef(tmpRoot, pushDigest), blobPath, "-v").
+			ORAS("blob", "push", Flags.Layout, LayoutRef(tmpRoot, pushDigest), blobPath).
 				WithDescription("skip pushing if the blob already exists in the target repo").
 				MatchKeyWords("Exists").Exec()
 			// validate