From 8b22600b4105d863bde7913809a3c3131c26f797 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 02:27:33 +0000
Subject: [PATCH 01/40] feat!: add flag for referrers GC

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 43 +++++++++++++++++++++++++++
 cmd/oras/root/attach.go               |  5 ++++
 cmd/oras/root/cp.go                   |  4 +++
 cmd/oras/root/manifest/delete.go      |  2 ++
 cmd/oras/root/manifest/push.go        |  4 +++
 go.mod                                |  2 ++
 go.sum                                |  2 --
 7 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 cmd/oras/internal/option/referrers.go

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
new file mode 100644
index 000000000..157c6df91
--- /dev/null
+++ b/cmd/oras/internal/option/referrers.go
@@ -0,0 +1,43 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package option
+
+import (
+	"errors"
+
+	"github.com/spf13/pflag"
+	"oras.land/oras-go/v2/registry/remote"
+)
+
+// Referrers option struct.
+type Referrers struct {
+	GC bool
+}
+
+// ApplyFlags applies flags to a command flag set.
+func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
+	fs.BoolVarP(&opts.GC, "referrers-gc", "", false, "enforce garbage collection when referrers API is not supported")
+}
+
+// SetReferrersGC sets the referrers GC option for the passed-in target.
+func (opts *Referrers) SetReferrersGC(target any) error {
+	repo, ok := target.(*remote.Repository)
+	if !ok {
+		return errors.New("referrers GC can only be enforced to registry targets")
+	}
+	repo.ReferrersGC = opts.GC
+	return nil
+}
diff --git a/cmd/oras/root/attach.go b/cmd/oras/root/attach.go
index a1032f67b..9de992440 100644
--- a/cmd/oras/root/attach.go
+++ b/cmd/oras/root/attach.go
@@ -35,6 +35,7 @@ type attachOptions struct {
 	option.Packer
 	option.ImageSpec
 	option.Target
+	option.Referrers
 
 	artifactType string
 	concurrency  int
@@ -122,6 +123,10 @@ func runAttach(ctx context.Context, opts attachOptions) error {
 	if err := opts.EnsureReferenceNotEmpty(); err != nil {
 		return err
 	}
+	if err = opts.SetReferrersGC(dst); err != nil {
+		return err
+	}
+
 	subject, err := dst.Resolve(ctx, opts.Reference)
 	if err != nil {
 		return err
diff --git a/cmd/oras/root/cp.go b/cmd/oras/root/cp.go
index 26b58d18c..5a1a07a24 100644
--- a/cmd/oras/root/cp.go
+++ b/cmd/oras/root/cp.go
@@ -34,6 +34,7 @@ type copyOptions struct {
 	option.Common
 	option.Platform
 	option.BinaryTarget
+	option.Referrers
 
 	recursive   bool
 	concurrency int
@@ -112,6 +113,9 @@ func runCopy(ctx context.Context, opts copyOptions) error {
 	if err != nil {
 		return err
 	}
+	if err = opts.SetReferrersGC(dst); err != nil {
+		return err
+	}
 
 	// Prepare copy options
 	committed := &sync.Map{}
diff --git a/cmd/oras/root/manifest/delete.go b/cmd/oras/root/manifest/delete.go
index 8ece10400..ea3c0df74 100644
--- a/cmd/oras/root/manifest/delete.go
+++ b/cmd/oras/root/manifest/delete.go
@@ -33,6 +33,7 @@ type deleteOptions struct {
 	option.Descriptor
 	option.Pretty
 	option.Remote
+	option.Referrers
 
 	targetRef string
 }
@@ -81,6 +82,7 @@ func deleteManifest(ctx context.Context, opts deleteOptions) error {
 	if err != nil {
 		return err
 	}
+	repo.ReferrersGC = opts.GC
 
 	if repo.Reference.Reference == "" {
 		return oerrors.NewErrInvalidReference(repo.Reference)
diff --git a/cmd/oras/root/manifest/push.go b/cmd/oras/root/manifest/push.go
index e7a86ef02..c0b115420 100644
--- a/cmd/oras/root/manifest/push.go
+++ b/cmd/oras/root/manifest/push.go
@@ -38,6 +38,7 @@ type pushOptions struct {
 	option.Descriptor
 	option.Pretty
 	option.Target
+	option.Referrers
 
 	concurrency int
 	extraRefs   []string
@@ -111,6 +112,9 @@ func pushManifest(ctx context.Context, opts pushOptions) error {
 	if err != nil {
 		return err
 	}
+	if err = opts.SetReferrersGC(target); err != nil {
+		return err
+	}
 	if repo, ok := target.(*remote.Repository); ok {
 		target = repo.Manifests()
 	}
diff --git a/go.mod b/go.mod
index eeca4a3af..1694218e4 100644
--- a/go.mod
+++ b/go.mod
@@ -2,6 +2,8 @@ module oras.land/oras
 
 go 1.20
 
+replace oras.land/oras-go/v2 => ../oras-go
+
 require (
 	github.com/need-being/go-tree v0.1.0
 	github.com/opencontainers/go-digest v1.0.0
diff --git a/go.sum b/go.sum
index 557409e44..303907013 100644
--- a/go.sum
+++ b/go.sum
@@ -38,5 +38,3 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-oras.land/oras-go/v2 v2.2.0 h1:E1fqITD56Eg5neZbxBtAdZVgDHD6wBabJo6xESTcQyo=
-oras.land/oras-go/v2 v2.2.0/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=

From 7b7e5a47bb9b652f60321c4bac8b2d8127e068e6 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 02:49:44 +0000
Subject: [PATCH 02/40] update go mod

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 go.mod | 2 +-
 go.sum | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/go.mod b/go.mod
index 1694218e4..f468f64b4 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => ../oras-go
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/go.sum b/go.sum
index 303907013..e1bc29c20 100644
--- a/go.sum
+++ b/go.sum
@@ -16,6 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=

From e27d723c35cfd5b699126f241f9b9451367fc85e Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 03:55:32 +0000
Subject: [PATCH 03/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 6 +++---
 test/e2e/go.mod                       | 2 ++
 test/e2e/go.sum                       | 4 ++--
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 157c6df91..7d883e1a1 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -34,10 +34,10 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.
 func (opts *Referrers) SetReferrersGC(target any) error {
-	repo, ok := target.(*remote.Repository)
-	if !ok {
+	if repo, ok := target.(*remote.Repository); ok {
+		repo.ReferrersGC = opts.GC
+	} else if opts.GC {
 		return errors.New("referrers GC can only be enforced to registry targets")
 	}
-	repo.ReferrersGC = opts.GC
 	return nil
 }
diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index 323e6e964..5aa928fa9 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,6 +2,8 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
+
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7
 	github.com/onsi/gomega v1.27.7
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index 5993ba3ff..1a742e0bf 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,6 +24,8 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
@@ -47,5 +49,3 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-oras.land/oras-go/v2 v2.2.0 h1:E1fqITD56Eg5neZbxBtAdZVgDHD6wBabJo6xESTcQyo=
-oras.land/oras-go/v2 v2.2.0/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=

From 57b4e75fbf6dc0e6c8f97fcc6da593aa275e6329 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 07:15:42 +0000
Subject: [PATCH 04/40] add e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/attach.go   | 10 ++++++++++
 test/e2e/suite/command/cp.go       |  6 ++++++
 test/e2e/suite/command/manifest.go | 10 ++++++++++
 3 files changed, 26 insertions(+)

diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 54c35f6c3..9d053f9b4 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -204,6 +204,16 @@ var _ = Describe("OCI image layout users:", func() {
 		prepare := func(root string) {
 			ORAS("cp", RegistryRef(Host, ImageRepo, foobar.Tag), Flags.ToLayout, LayoutRef(root, foobar.Tag)).Exec()
 		}
+
+		It("should fail to specify referrers garbage collection", func() {
+			root := PrepareTempFiles()
+			subjectRef := LayoutRef(root, foobar.Tag)
+			ORAS("attach", "--artifact-type", "test.attach", "--referrers-gc", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				ExpectFailure().
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				Exec()
+		})
+
 		It("should attach a file to a subject", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 4b49187fa..0f0a51911 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -323,6 +323,12 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
+		It("should fail to specify referrers garbage collection", func() {
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--referrers-gc").
+				ExpectFailure().
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				Exec()
+		})
 		It("should copy an image from a registry to an OCI image layout via tag", func() {
 			dst := LayoutRef(GinkgoT().TempDir(), "copied")
 			src := RegistryRef(Host, ImageRepo, foobar.Tag)
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index a0c6cec55..b31b10e3e 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -547,6 +547,15 @@ var _ = Describe("OCI image layout users:", func() {
 		}
 		descriptor := "{\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"digest\":\"sha256:f20c43161d73848408ef247f0ec7111b19fe58ffebc0cbcaa0d2c8bda4967268\",\"size\":246}"
 
+		It("should fail to specify referrers garbage collection", func() {
+			manifestPath := WriteTempFile("manifest.json", manifest)
+			root := filepath.Dir(manifestPath)
+			ORAS("manifest", "push", Flags.Layout, manifestPath).
+				WithWorkDir(root).
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				ExpectFailure().Exec()
+		})
+
 		It("should push a manifest from stdin", func() {
 			root := GinkgoT().TempDir()
 			prepare(root)
@@ -555,6 +564,7 @@ var _ = Describe("OCI image layout users:", func() {
 				WithInput(strings.NewReader(manifest)).Exec()
 			validate(root, manifestDigest, "")
 		})
+
 		It("should push a manifest from stdin and tag", func() {
 			tag := "from-stdin"
 			root := GinkgoT().TempDir()

From adfcca184350cadb22e405893fe87f3344cd5c55 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 08:59:04 +0000
Subject: [PATCH 05/40] update deps

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 2 +-
 go.mod                                | 2 +-
 go.sum                                | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 7d883e1a1..152299a48 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -35,7 +35,7 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 // SetReferrersGC sets the referrers GC option for the passed-in target.
 func (opts *Referrers) SetReferrersGC(target any) error {
 	if repo, ok := target.(*remote.Repository); ok {
-		repo.ReferrersGC = opts.GC
+		repo.SkipReferrersGC = !opts.GC
 	} else if opts.GC {
 		return errors.New("referrers GC can only be enforced to registry targets")
 	}
diff --git a/go.mod b/go.mod
index f468f64b4..fe2998ad3 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/go.sum b/go.sum
index e1bc29c20..0f7b25407 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed h1:yIhtSuHvrHQHDiTfGSFt366Z3qDQe0kQoqlH3Uu3bbA=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=

From cacd6bb3c14532cc51749e4b407948316f80c771 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 00:50:52 +0000
Subject: [PATCH 06/40] update dep

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/root/manifest/delete.go | 2 +-
 go.mod                           | 2 +-
 go.sum                           | 4 ++--
 test/e2e/go.mod                  | 2 +-
 test/e2e/go.sum                  | 4 ++--
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/cmd/oras/root/manifest/delete.go b/cmd/oras/root/manifest/delete.go
index ea3c0df74..dff2e8d87 100644
--- a/cmd/oras/root/manifest/delete.go
+++ b/cmd/oras/root/manifest/delete.go
@@ -82,7 +82,7 @@ func deleteManifest(ctx context.Context, opts deleteOptions) error {
 	if err != nil {
 		return err
 	}
-	repo.ReferrersGC = opts.GC
+	repo.SkipReferrersGC = !opts.GC
 
 	if repo.Reference.Reference == "" {
 		return oerrors.NewErrInvalidReference(repo.Reference)
diff --git a/go.mod b/go.mod
index fe2998ad3..889ad699a 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/go.sum b/go.sum
index 0f7b25407..f1bef059e 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed h1:yIhtSuHvrHQHDiTfGSFt366Z3qDQe0kQoqlH3Uu3bbA=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index 5aa928fa9..d082c222c 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
 
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index 1a742e0bf..bc5048597 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,8 +24,8 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=

From f0ecebf511f3c81b1dd7169b80a535b26b558383 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 07:21:30 +0000
Subject: [PATCH 07/40] update

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/go.mod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index d082c222c..5df09c9cf 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
 
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7

From ffbd8bc379d829218ecf80862510363c86b88a28 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 07:28:16 +0000
Subject: [PATCH 08/40] update version

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 go.mod          | 2 +-
 test/e2e/go.sum | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/go.mod b/go.mod
index 889ad699a..21bf634c7 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index bc5048597..f576b8fed 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,8 +24,8 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=

From d5f1937cb2ea00ffb4f5451575781a6709eda97d Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 07:43:10 +0000
Subject: [PATCH 09/40] mod tidy

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 go.sum | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/go.sum b/go.sum
index f1bef059e..e5b482fca 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=

From abae5241d9b3f069b46080e647655f98d10f7a49 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 08:03:13 +0000
Subject: [PATCH 10/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/manifest.go | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index b31b10e3e..5369f8e6e 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -550,10 +550,10 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
-			ORAS("manifest", "push", Flags.Layout, manifestPath).
+			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--referrers-gc").
 				WithWorkDir(root).
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
-				ExpectFailure().Exec()
+				ExpectFailure().
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").Exec()
 		})
 
 		It("should push a manifest from stdin", func() {

From 06d382d32b7ac35a90d2199b6b563402d1debd58 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 1 Jun 2023 00:26:21 +0000
Subject: [PATCH 11/40] rename flag

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 8 ++++----
 cmd/oras/root/manifest/delete.go      | 2 +-
 go.mod                                | 4 +---
 go.sum                                | 6 ++++--
 test/e2e/go.mod                       | 4 +---
 test/e2e/go.sum                       | 4 ++--
 test/e2e/suite/command/attach.go      | 2 +-
 test/e2e/suite/command/cp.go          | 2 +-
 test/e2e/suite/command/manifest.go    | 2 +-
 9 files changed, 16 insertions(+), 18 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 152299a48..54cec6c6f 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -24,19 +24,19 @@ import (
 
 // Referrers option struct.
 type Referrers struct {
-	GC bool
+	SkipDeleteReferrers bool
 }
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
-	fs.BoolVarP(&opts.GC, "referrers-gc", "", false, "enforce garbage collection when referrers API is not supported")
+	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", false, "skip deleting old referrers index, only work on registry when referrers API is not supported")
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.
 func (opts *Referrers) SetReferrersGC(target any) error {
 	if repo, ok := target.(*remote.Repository); ok {
-		repo.SkipReferrersGC = !opts.GC
-	} else if opts.GC {
+		repo.SkipReferrersGC = opts.SkipDeleteReferrers
+	} else if opts.SkipDeleteReferrers {
 		return errors.New("referrers GC can only be enforced to registry targets")
 	}
 	return nil
diff --git a/cmd/oras/root/manifest/delete.go b/cmd/oras/root/manifest/delete.go
index dff2e8d87..d347d2b2c 100644
--- a/cmd/oras/root/manifest/delete.go
+++ b/cmd/oras/root/manifest/delete.go
@@ -82,7 +82,7 @@ func deleteManifest(ctx context.Context, opts deleteOptions) error {
 	if err != nil {
 		return err
 	}
-	repo.SkipReferrersGC = !opts.GC
+	repo.SkipReferrersGC = opts.SkipDeleteReferrers
 
 	if repo.Reference.Reference == "" {
 		return oerrors.NewErrInvalidReference(repo.Reference)
diff --git a/go.mod b/go.mod
index 21bf634c7..fabcdff52 100644
--- a/go.mod
+++ b/go.mod
@@ -2,8 +2,6 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
-
 require (
 	github.com/need-being/go-tree v0.1.0
 	github.com/opencontainers/go-digest v1.0.0
@@ -14,7 +12,7 @@ require (
 	github.com/spf13/pflag v1.0.5
 	golang.org/x/term v0.8.0
 	gopkg.in/yaml.v3 v3.0.1
-	oras.land/oras-go/v2 v2.2.0
+	oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6
 )
 
 require (
diff --git a/go.sum b/go.sum
index e5b482fca..7814d36a9 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,6 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
@@ -40,3 +38,7 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+oras.land/oras-go/v2 v2.2.0 h1:E1fqITD56Eg5neZbxBtAdZVgDHD6wBabJo6xESTcQyo=
+oras.land/oras-go/v2 v2.2.0/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6 h1:2P1fjq1znGLo7tjy9PJsZrFF5L+qywbv28IgzKEX62E=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index 5df09c9cf..d31b3591a 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,15 +2,13 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
-
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7
 	github.com/onsi/gomega v1.27.7
 	github.com/opencontainers/go-digest v1.0.0
 	github.com/opencontainers/image-spec v1.1.0-rc.3
 	gopkg.in/yaml.v2 v2.4.0
-	oras.land/oras-go/v2 v2.2.0
+	oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6
 )
 
 require (
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index f576b8fed..7d79a95e7 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,8 +24,6 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
@@ -49,3 +47,5 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6 h1:2P1fjq1znGLo7tjy9PJsZrFF5L+qywbv28IgzKEX62E=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 9d053f9b4..e7ee5bdae 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -208,7 +208,7 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
-			ORAS("attach", "--artifact-type", "test.attach", "--referrers-gc", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
 				ExpectFailure().
 				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
 				Exec()
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 0f0a51911..bd8dd883e 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -324,7 +324,7 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
 		It("should fail to specify referrers garbage collection", func() {
-			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--referrers-gc").
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers").
 				ExpectFailure().
 				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
 				Exec()
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 5369f8e6e..600a6676b 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -550,7 +550,7 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
-			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--referrers-gc").
+			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers").
 				WithWorkDir(root).
 				ExpectFailure().
 				MatchContent("Error: referrers GC can only be enforced to registry targets\n").Exec()

From 86f3b1dfabad245df0b2b69bceb4ee8585ece454 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Fri, 2 Jun 2023 10:21:30 +0000
Subject: [PATCH 12/40] fix: default to true

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 54cec6c6f..09da031df 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -29,7 +29,7 @@ type Referrers struct {
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
-	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", false, "skip deleting old referrers index, only work on registry when referrers API is not supported")
+	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", true, "skip deleting old referrers index, only work on registry when referrers API is not supported")
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.

From 19c45165b170c03a9b3dd5fd8c8c9cf57dd1bd74 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Fri, 2 Jun 2023 10:30:32 +0000
Subject: [PATCH 13/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 4 ++--
 test/e2e/suite/command/attach.go      | 4 ++--
 test/e2e/suite/command/cp.go          | 4 ++--
 test/e2e/suite/command/manifest.go    | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 09da031df..40074c1ee 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -36,8 +36,8 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 func (opts *Referrers) SetReferrersGC(target any) error {
 	if repo, ok := target.(*remote.Repository); ok {
 		repo.SkipReferrersGC = opts.SkipDeleteReferrers
-	} else if opts.SkipDeleteReferrers {
-		return errors.New("referrers GC can only be enforced to registry targets")
+	} else if !opts.SkipDeleteReferrers {
+		return errors.New("referrers deletion can only be enforced upon registry targets")
 	}
 	return nil
 }
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index e7ee5bdae..b36c7e9d5 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -208,9 +208,9 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
-			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers=false", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
 				ExpectFailure().
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
 				Exec()
 		})
 
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index bd8dd883e..161782d23 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -324,9 +324,9 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
 		It("should fail to specify referrers garbage collection", func() {
-			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers").
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers=false").
 				ExpectFailure().
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
 				Exec()
 		})
 		It("should copy an image from a registry to an OCI image layout via tag", func() {
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 600a6676b..e190d2cd0 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -550,10 +550,10 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
-			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers").
+			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers=false").
 				WithWorkDir(root).
 				ExpectFailure().
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").Exec()
+				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").Exec()
 		})
 
 		It("should push a manifest from stdin", func() {

From 623dc9912843f63cd2cc54d4a553b03b435e1613 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 00:52:02 +0000
Subject: [PATCH 14/40] change default value to false

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 40074c1ee..d9b16a431 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -29,7 +29,7 @@ type Referrers struct {
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
-	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", true, "skip deleting old referrers index, only work on registry when referrers API is not supported")
+	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", false, "skip deleting old referrers index, only work on registry when referrers API is not supported")
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.

From aa73bc9784bd1fa2a5cc65838ff98de2b8b0558d Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 01:31:38 +0000
Subject: [PATCH 15/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go |  8 +++-----
 cmd/oras/root/attach.go               |  6 ++----
 cmd/oras/root/cp.go                   |  6 ++----
 cmd/oras/root/manifest/push.go        |  6 ++----
 test/e2e/suite/command/attach.go      | 18 +++++++++---------
 test/e2e/suite/command/cp.go          | 12 ++++++------
 test/e2e/suite/command/manifest.go    |  6 +++---
 7 files changed, 27 insertions(+), 35 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index d9b16a431..9284788a3 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -16,8 +16,7 @@ limitations under the License.
 package option
 
 import (
-	"errors"
-
+	"github.com/sirupsen/logrus"
 	"github.com/spf13/pflag"
 	"oras.land/oras-go/v2/registry/remote"
 )
@@ -33,11 +32,10 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.
-func (opts *Referrers) SetReferrersGC(target any) error {
+func (opts *Referrers) SetReferrersGC(target any, logger logrus.FieldLogger) {
 	if repo, ok := target.(*remote.Repository); ok {
 		repo.SkipReferrersGC = opts.SkipDeleteReferrers
 	} else if !opts.SkipDeleteReferrers {
-		return errors.New("referrers deletion can only be enforced upon registry targets")
+		logger.Warnln("referrers deletion can only be enforced upon registry")
 	}
-	return nil
 }
diff --git a/cmd/oras/root/attach.go b/cmd/oras/root/attach.go
index 9de992440..69d4f7f6b 100644
--- a/cmd/oras/root/attach.go
+++ b/cmd/oras/root/attach.go
@@ -99,7 +99,7 @@ Example - Attach file to the manifest tagged 'v1' in an OCI layout folder 'layou
 }
 
 func runAttach(ctx context.Context, opts attachOptions) error {
-	ctx, _ = opts.WithContext(ctx)
+	ctx, logger := opts.WithContext(ctx)
 	annotations, err := opts.LoadManifestAnnotations()
 	if err != nil {
 		return err
@@ -123,9 +123,7 @@ func runAttach(ctx context.Context, opts attachOptions) error {
 	if err := opts.EnsureReferenceNotEmpty(); err != nil {
 		return err
 	}
-	if err = opts.SetReferrersGC(dst); err != nil {
-		return err
-	}
+	opts.SetReferrersGC(dst, logger)
 
 	subject, err := dst.Resolve(ctx, opts.Reference)
 	if err != nil {
diff --git a/cmd/oras/root/cp.go b/cmd/oras/root/cp.go
index 5a1a07a24..5e0982625 100644
--- a/cmd/oras/root/cp.go
+++ b/cmd/oras/root/cp.go
@@ -97,7 +97,7 @@ Example - Copy an artifact with multiple tags with concurrency tuned:
 }
 
 func runCopy(ctx context.Context, opts copyOptions) error {
-	ctx, _ = opts.WithContext(ctx)
+	ctx, logger := opts.WithContext(ctx)
 
 	// Prepare source
 	src, err := opts.From.NewReadonlyTarget(ctx, opts.Common)
@@ -113,9 +113,7 @@ func runCopy(ctx context.Context, opts copyOptions) error {
 	if err != nil {
 		return err
 	}
-	if err = opts.SetReferrersGC(dst); err != nil {
-		return err
-	}
+	opts.SetReferrersGC(dst, logger)
 
 	// Prepare copy options
 	committed := &sync.Map{}
diff --git a/cmd/oras/root/manifest/push.go b/cmd/oras/root/manifest/push.go
index c0b115420..1d3e8ce08 100644
--- a/cmd/oras/root/manifest/push.go
+++ b/cmd/oras/root/manifest/push.go
@@ -105,16 +105,14 @@ Example - Push a manifest to an OCI layout folder 'layout-dir' and tag with 'v1'
 }
 
 func pushManifest(ctx context.Context, opts pushOptions) error {
-	ctx, _ = opts.WithContext(ctx)
+	ctx, logger := opts.WithContext(ctx)
 	var target oras.Target
 	var err error
 	target, err = opts.NewTarget(opts.Common)
 	if err != nil {
 		return err
 	}
-	if err = opts.SetReferrersGC(target); err != nil {
-		return err
-	}
+	opts.SetReferrersGC(target, logger)
 	if repo, ok := target.(*remote.Repository); ok {
 		target = repo.Manifests()
 	}
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index b36c7e9d5..9896acd56 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -205,15 +205,6 @@ var _ = Describe("OCI image layout users:", func() {
 			ORAS("cp", RegistryRef(Host, ImageRepo, foobar.Tag), Flags.ToLayout, LayoutRef(root, foobar.Tag)).Exec()
 		}
 
-		It("should fail to specify referrers garbage collection", func() {
-			root := PrepareTempFiles()
-			subjectRef := LayoutRef(root, foobar.Tag)
-			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers=false", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
-				ExpectFailure().
-				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
-				Exec()
-		})
-
 		It("should attach a file to a subject", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
@@ -223,6 +214,15 @@ var _ = Describe("OCI image layout users:", func() {
 				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
 		})
 
+		It("should attach and output warning for referrers deletion by default", func() {
+			root := PrepareTempFiles()
+			subjectRef := LayoutRef(root, foobar.Tag)
+			prepare(root)
+			ORAS("attach", "--artifact-type", "test.attach", "-v", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				MatchContent("Error: referrers deletion can only be enforced upon registry\n").
+				Exec()
+		})
+
 		It("should attach a file to a subject and export the built manifest", func() {
 			// prepare
 			root := PrepareTempFiles()
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 161782d23..d5decaa3f 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -323,12 +323,6 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
-		It("should fail to specify referrers garbage collection", func() {
-			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers=false").
-				ExpectFailure().
-				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
-				Exec()
-		})
 		It("should copy an image from a registry to an OCI image layout via tag", func() {
 			dst := LayoutRef(GinkgoT().TempDir(), "copied")
 			src := RegistryRef(Host, ImageRepo, foobar.Tag)
@@ -339,6 +333,12 @@ var _ = Describe("OCI layout users:", func() {
 			Expect(srcManifest).To(Equal(dstManifest))
 		})
 
+		It("should copy and output verbosed warning for Feferrers deletion by default", func() {
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "-v").
+				MatchErrKeyWords("referrers deletion can only be enforced upon registry\n").
+				Exec()
+		})
+
 		It("should copy an image from an OCI image layout to a registry via tag", func() {
 			layoutDir := GinkgoT().TempDir()
 			src := LayoutRef(layoutDir, "copied")
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index e190d2cd0..9cf86543c 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -547,13 +547,13 @@ var _ = Describe("OCI image layout users:", func() {
 		}
 		descriptor := "{\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"digest\":\"sha256:f20c43161d73848408ef247f0ec7111b19fe58ffebc0cbcaa0d2c8bda4967268\",\"size\":246}"
 
-		It("should fail to specify referrers garbage collection", func() {
+		It("should push and output verbosed warning for Feferrers deletion by default", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
+			prepare(root)
 			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers=false").
 				WithWorkDir(root).
-				ExpectFailure().
-				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").Exec()
+				MatchErrKeyWords("referrers deletion can only be enforced upon registry\n").Exec()
 		})
 
 		It("should push a manifest from stdin", func() {

From aa9149363804a30d7c4661966dbb652584b3712a Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 01:40:08 +0000
Subject: [PATCH 16/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/attach.go | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 9896acd56..1878bfea2 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -219,7 +219,8 @@ var _ = Describe("OCI image layout users:", func() {
 			subjectRef := LayoutRef(root, foobar.Tag)
 			prepare(root)
 			ORAS("attach", "--artifact-type", "test.attach", "-v", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
-				MatchContent("Error: referrers deletion can only be enforced upon registry\n").
+				MatchErrKeyWords("referrers deletion can only be enforced upon registry\n").
+				WithWorkDir(root).
 				Exec()
 		})
 

From 06af37b6b2b641ddbdc3ccbd53a185b82c6151eb Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 05:50:07 +0000
Subject: [PATCH 17/40] refactor: simplify e2e scripts and github action

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 .github/workflows/build.yml     |  8 +++++---
 Makefile                        | 10 +++++++---
 test/e2e/internal/utils/exec.go |  1 -
 test/e2e/internal/utils/init.go | 14 +++-----------
 test/e2e/scripts/e2e.sh         | 10 ----------
 5 files changed, 15 insertions(+), 28 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index ee8344f19..f7c7a38d6 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -43,11 +43,13 @@ jobs:
         run: make test
       - name: Run E2E Tests
         run: |
-          bash $GITHUB_WORKSPACE/test/e2e/scripts/e2e.sh $GITHUB_WORKSPACE --clean
-          make e2e-covdata
+          if [[ $GITHUB_REF_NAME == v* && $GITHUB_REF_TYPE == tag ]]; then
+            make teste2e
+          else
+            make teste2e-covdata
+          fi
         env:
           ORAS_PATH: bin/linux/amd64/oras
-          COVERAGE_DUMP_ROOT: .cover
       - name: Check Version
         run: bin/linux/amd64/oras version
       - name: Upload coverage to codecov.io
diff --git a/Makefile b/Makefile
index 355249301..081cafe98 100644
--- a/Makefile
+++ b/Makefile
@@ -129,6 +129,10 @@ sign:
 		gpg --armor --detach-sign $${f} ; \
 	done
 
-.PHONY: e2e-covdata
-e2e-covdata:
-	$(GO_EXE) tool covdata textfmt -i="test/e2e/${COVERAGE_DUMP_ROOT}" -o test/e2e/coverage.txt
+.PHONY: teste2e-covdata
+teste2e-covdata
+	export GOCOVERDIR=$(CURDIR)/test/e2e/.cover; \
+	rm -rf $$GOCOVERDIR; \
+	mkdir -p $$GOCOVERDIR; \
+	$(MAKE) teste2e; \
+	$(GO_EXE) tool covdata textfmt -i=$$COVERAGE_DUMP_ROOT -o "$(CURDIR)/test/e2e/coverage.txt"
\ No newline at end of file
diff --git a/test/e2e/internal/utils/exec.go b/test/e2e/internal/utils/exec.go
index a998828da..b827ba019 100644
--- a/test/e2e/internal/utils/exec.go
+++ b/test/e2e/internal/utils/exec.go
@@ -189,7 +189,6 @@ func (opts *ExecOption) Exec() *gexec.Session {
 		opts.binary = ORASPath
 	}
 	cmd = exec.Command(opts.binary, opts.args...)
-	cmd.Env = append(os.Environ(), fmt.Sprintf("GOCOVERDIR=%s", CovDumpPath))
 	cmd.Stdin = opts.stdin
 	if opts.workDir != "" {
 		// switch working directory
diff --git a/test/e2e/internal/utils/init.go b/test/e2e/internal/utils/init.go
index 1928d83d7..d1be20ba9 100644
--- a/test/e2e/internal/utils/init.go
+++ b/test/e2e/internal/utils/init.go
@@ -75,24 +75,16 @@ func init() {
 	}
 	BeforeSuite(func() {
 		ORASPath = os.Getenv("ORAS_PATH")
-		if covDumpRoot := os.Getenv("COVERAGE_DUMP_ROOT"); covDumpRoot != "" {
+		if CovDumpPath := os.Getenv("GOCOVERDIR"); CovDumpPath != "" {
+			fmt.Printf("Coverage file dump path: %q\n", CovDumpPath)
 			if ORASPath != "" {
-				fmt.Printf("Pre-built oras ignored: %s\n", ORASPath)
+				fmt.Printf("Pre-built oras in %q will be ignored\n", ORASPath)
 				ORASPath = ""
 			}
-			if filepath.IsAbs(covDumpRoot) {
-				CovDumpPath = covDumpRoot
-			} else if workspacePath := os.Getenv("GITHUB_WORKSPACE"); workspacePath != "" {
-				CovDumpPath = filepath.Join(workspacePath, "test/e2e", covDumpRoot)
-			} else {
-				// local debugging
-				CovDumpPath = filepath.Join(pwd, "..", "..", covDumpRoot)
-			}
 
 			// confirm the existence of dump folder
 			err := os.MkdirAll(CovDumpPath, 0700)
 			gomega.Expect(err).NotTo(gomega.HaveOccurred())
-			fmt.Printf("Coverage file dump path: %q\n", CovDumpPath)
 		}
 		if filepath.IsAbs(ORASPath) {
 			fmt.Printf("Testing based on pre-built binary locates in %q\n", ORASPath)
diff --git a/test/e2e/scripts/e2e.sh b/test/e2e/scripts/e2e.sh
index 9847e2d7b..b110e38c6 100755
--- a/test/e2e/scripts/e2e.sh
+++ b/test/e2e/scripts/e2e.sh
@@ -58,16 +58,6 @@ run_registry \
   $upstream_container_name \
   $ORAS_REGISTRY_FALLBACK_PORT
 
-echo " === setup coverage instrumenting == "
-if [[ $GITHUB_REF_NAME == v* && $GITHUB_REF_TYPE == tag ]]; then
-    echo "coverage instrumentation skipped"
-    unset COVERAGE_DUMP_ROOT
-fi
-
-if ! [ -z ${COVERAGE_DUMP_ROOT} ]; then
-  rm ${e2e_root}/${COVERAGE_DUMP_ROOT} -rf
-fi
-
 echo " === run tests === "
 if ! ginkgo -r -p --succinct suite; then 
   echo " === retriving registry error logs === "

From f78e02d12328cdfa35ad373cd4d0fbd7b209c8c9 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 05:55:22 +0000
Subject: [PATCH 18/40] fix makefile

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 081cafe98..6cbe03c6b 100644
--- a/Makefile
+++ b/Makefile
@@ -130,7 +130,7 @@ sign:
 	done
 
 .PHONY: teste2e-covdata
-teste2e-covdata
+teste2e-covdata:
 	export GOCOVERDIR=$(CURDIR)/test/e2e/.cover; \
 	rm -rf $$GOCOVERDIR; \
 	mkdir -p $$GOCOVERDIR; \

From 3b2f883a875ac02a8bdcaa9fa5c812869e020521 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 06:35:22 +0000
Subject: [PATCH 19/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 6cbe03c6b..1749c3cbd 100644
--- a/Makefile
+++ b/Makefile
@@ -135,4 +135,4 @@ teste2e-covdata:
 	rm -rf $$GOCOVERDIR; \
 	mkdir -p $$GOCOVERDIR; \
 	$(MAKE) teste2e; \
-	$(GO_EXE) tool covdata textfmt -i=$$COVERAGE_DUMP_ROOT -o "$(CURDIR)/test/e2e/coverage.txt"
\ No newline at end of file
+	$(GO_EXE) tool covdata textfmt -i=$$GOCOVERDIR -o "$(CURDIR)/test/e2e/coverage.txt"
\ No newline at end of file

From 5d1b6f23f155ed619d4cfdc7931669a6c7d1c400 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 07:33:10 +0000
Subject: [PATCH 20/40] remove global coverage dump path

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/internal/utils/init.go | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/test/e2e/internal/utils/init.go b/test/e2e/internal/utils/init.go
index d1be20ba9..ecefaa3ad 100644
--- a/test/e2e/internal/utils/init.go
+++ b/test/e2e/internal/utils/init.go
@@ -36,9 +36,6 @@ var Host string
 // FallbackHost points to the registry service where fallback E2E specs will be run against.
 var FallbackHost string
 
-// Path to generate the coverage report.
-var CovDumpPath string
-
 func init() {
 	Host = os.Getenv(RegHostKey)
 	if Host == "" {
@@ -75,17 +72,19 @@ func init() {
 	}
 	BeforeSuite(func() {
 		ORASPath = os.Getenv("ORAS_PATH")
-		if CovDumpPath := os.Getenv("GOCOVERDIR"); CovDumpPath != "" {
-			fmt.Printf("Coverage file dump path: %q\n", CovDumpPath)
+		var covDumpPath string
+		if covDumpPath = os.Getenv("GOCOVERDIR"); covDumpPath != "" {
+			fmt.Printf("Coverage file dump path: %q\n", covDumpPath)
 			if ORASPath != "" {
 				fmt.Printf("Pre-built oras in %q will be ignored\n", ORASPath)
 				ORASPath = ""
 			}
 
 			// confirm the existence of dump folder
-			err := os.MkdirAll(CovDumpPath, 0700)
+			err := os.MkdirAll(covDumpPath, 0700)
 			gomega.Expect(err).NotTo(gomega.HaveOccurred())
 		}
+
 		if filepath.IsAbs(ORASPath) {
 			fmt.Printf("Testing based on pre-built binary locates in %q\n", ORASPath)
 		} else if workspacePath := os.Getenv("GITHUB_WORKSPACE"); ORASPath != "" && workspacePath != "" {
@@ -97,7 +96,8 @@ func init() {
 		} else {
 			// fallback to native build to facilitate local debugging
 			buildArgs := []string{}
-			if CovDumpPath != "" {
+			if covDumpPath != "" {
+				fmt.Printf("coverage instrumenting is enabled\n")
 				buildArgs = append(buildArgs, "-coverpkg", "oras.land/oras/cmd/oras/...,oras.land/oras/internal/...")
 			}
 			ORASPath, err = gexec.Build("oras.land/oras/cmd/oras", buildArgs...)

From 71a15515b043570fba812e21f4598bcfadb30731 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 02:27:33 +0000
Subject: [PATCH 21/40] feat!: add flag for referrers GC

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 43 +++++++++++++++++++++++++++
 cmd/oras/root/attach.go               |  5 ++++
 cmd/oras/root/cp.go                   |  4 +++
 cmd/oras/root/manifest/delete.go      |  2 ++
 cmd/oras/root/manifest/push.go        |  4 +++
 go.mod                                |  2 ++
 go.sum                                |  2 --
 7 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 cmd/oras/internal/option/referrers.go

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
new file mode 100644
index 000000000..157c6df91
--- /dev/null
+++ b/cmd/oras/internal/option/referrers.go
@@ -0,0 +1,43 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package option
+
+import (
+	"errors"
+
+	"github.com/spf13/pflag"
+	"oras.land/oras-go/v2/registry/remote"
+)
+
+// Referrers option struct.
+type Referrers struct {
+	GC bool
+}
+
+// ApplyFlags applies flags to a command flag set.
+func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
+	fs.BoolVarP(&opts.GC, "referrers-gc", "", false, "enforce garbage collection when referrers API is not supported")
+}
+
+// SetReferrersGC sets the referrers GC option for the passed-in target.
+func (opts *Referrers) SetReferrersGC(target any) error {
+	repo, ok := target.(*remote.Repository)
+	if !ok {
+		return errors.New("referrers GC can only be enforced to registry targets")
+	}
+	repo.ReferrersGC = opts.GC
+	return nil
+}
diff --git a/cmd/oras/root/attach.go b/cmd/oras/root/attach.go
index a1032f67b..9de992440 100644
--- a/cmd/oras/root/attach.go
+++ b/cmd/oras/root/attach.go
@@ -35,6 +35,7 @@ type attachOptions struct {
 	option.Packer
 	option.ImageSpec
 	option.Target
+	option.Referrers
 
 	artifactType string
 	concurrency  int
@@ -122,6 +123,10 @@ func runAttach(ctx context.Context, opts attachOptions) error {
 	if err := opts.EnsureReferenceNotEmpty(); err != nil {
 		return err
 	}
+	if err = opts.SetReferrersGC(dst); err != nil {
+		return err
+	}
+
 	subject, err := dst.Resolve(ctx, opts.Reference)
 	if err != nil {
 		return err
diff --git a/cmd/oras/root/cp.go b/cmd/oras/root/cp.go
index 26b58d18c..5a1a07a24 100644
--- a/cmd/oras/root/cp.go
+++ b/cmd/oras/root/cp.go
@@ -34,6 +34,7 @@ type copyOptions struct {
 	option.Common
 	option.Platform
 	option.BinaryTarget
+	option.Referrers
 
 	recursive   bool
 	concurrency int
@@ -112,6 +113,9 @@ func runCopy(ctx context.Context, opts copyOptions) error {
 	if err != nil {
 		return err
 	}
+	if err = opts.SetReferrersGC(dst); err != nil {
+		return err
+	}
 
 	// Prepare copy options
 	committed := &sync.Map{}
diff --git a/cmd/oras/root/manifest/delete.go b/cmd/oras/root/manifest/delete.go
index 8ece10400..ea3c0df74 100644
--- a/cmd/oras/root/manifest/delete.go
+++ b/cmd/oras/root/manifest/delete.go
@@ -33,6 +33,7 @@ type deleteOptions struct {
 	option.Descriptor
 	option.Pretty
 	option.Remote
+	option.Referrers
 
 	targetRef string
 }
@@ -81,6 +82,7 @@ func deleteManifest(ctx context.Context, opts deleteOptions) error {
 	if err != nil {
 		return err
 	}
+	repo.ReferrersGC = opts.GC
 
 	if repo.Reference.Reference == "" {
 		return oerrors.NewErrInvalidReference(repo.Reference)
diff --git a/cmd/oras/root/manifest/push.go b/cmd/oras/root/manifest/push.go
index e7a86ef02..c0b115420 100644
--- a/cmd/oras/root/manifest/push.go
+++ b/cmd/oras/root/manifest/push.go
@@ -38,6 +38,7 @@ type pushOptions struct {
 	option.Descriptor
 	option.Pretty
 	option.Target
+	option.Referrers
 
 	concurrency int
 	extraRefs   []string
@@ -111,6 +112,9 @@ func pushManifest(ctx context.Context, opts pushOptions) error {
 	if err != nil {
 		return err
 	}
+	if err = opts.SetReferrersGC(target); err != nil {
+		return err
+	}
 	if repo, ok := target.(*remote.Repository); ok {
 		target = repo.Manifests()
 	}
diff --git a/go.mod b/go.mod
index eeca4a3af..1694218e4 100644
--- a/go.mod
+++ b/go.mod
@@ -2,6 +2,8 @@ module oras.land/oras
 
 go 1.20
 
+replace oras.land/oras-go/v2 => ../oras-go
+
 require (
 	github.com/need-being/go-tree v0.1.0
 	github.com/opencontainers/go-digest v1.0.0
diff --git a/go.sum b/go.sum
index 557409e44..303907013 100644
--- a/go.sum
+++ b/go.sum
@@ -38,5 +38,3 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-oras.land/oras-go/v2 v2.2.0 h1:E1fqITD56Eg5neZbxBtAdZVgDHD6wBabJo6xESTcQyo=
-oras.land/oras-go/v2 v2.2.0/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=

From 8c34fb343dc65b719a1501a5f113b0899e5d9532 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 02:49:44 +0000
Subject: [PATCH 22/40] update go mod

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 go.mod | 2 +-
 go.sum | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/go.mod b/go.mod
index 1694218e4..f468f64b4 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => ../oras-go
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/go.sum b/go.sum
index 303907013..e1bc29c20 100644
--- a/go.sum
+++ b/go.sum
@@ -16,6 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=

From f0ddea573ec471e0a9678e43c54a362d39aa4e12 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 03:55:32 +0000
Subject: [PATCH 23/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 6 +++---
 test/e2e/go.mod                       | 2 ++
 test/e2e/go.sum                       | 4 ++--
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 157c6df91..7d883e1a1 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -34,10 +34,10 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.
 func (opts *Referrers) SetReferrersGC(target any) error {
-	repo, ok := target.(*remote.Repository)
-	if !ok {
+	if repo, ok := target.(*remote.Repository); ok {
+		repo.ReferrersGC = opts.GC
+	} else if opts.GC {
 		return errors.New("referrers GC can only be enforced to registry targets")
 	}
-	repo.ReferrersGC = opts.GC
 	return nil
 }
diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index 323e6e964..5aa928fa9 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,6 +2,8 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
+
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7
 	github.com/onsi/gomega v1.27.7
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index 5993ba3ff..1a742e0bf 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,6 +24,8 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
@@ -47,5 +49,3 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-oras.land/oras-go/v2 v2.2.0 h1:E1fqITD56Eg5neZbxBtAdZVgDHD6wBabJo6xESTcQyo=
-oras.land/oras-go/v2 v2.2.0/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=

From d5d1b7542e50094a1f2a8a7ebe0bd54d8570f2c5 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 07:15:42 +0000
Subject: [PATCH 24/40] add e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/attach.go   | 10 ++++++++++
 test/e2e/suite/command/cp.go       |  6 ++++++
 test/e2e/suite/command/manifest.go | 10 ++++++++++
 3 files changed, 26 insertions(+)

diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 54c35f6c3..9d053f9b4 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -204,6 +204,16 @@ var _ = Describe("OCI image layout users:", func() {
 		prepare := func(root string) {
 			ORAS("cp", RegistryRef(Host, ImageRepo, foobar.Tag), Flags.ToLayout, LayoutRef(root, foobar.Tag)).Exec()
 		}
+
+		It("should fail to specify referrers garbage collection", func() {
+			root := PrepareTempFiles()
+			subjectRef := LayoutRef(root, foobar.Tag)
+			ORAS("attach", "--artifact-type", "test.attach", "--referrers-gc", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				ExpectFailure().
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				Exec()
+		})
+
 		It("should attach a file to a subject", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 4b49187fa..0f0a51911 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -323,6 +323,12 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
+		It("should fail to specify referrers garbage collection", func() {
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--referrers-gc").
+				ExpectFailure().
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				Exec()
+		})
 		It("should copy an image from a registry to an OCI image layout via tag", func() {
 			dst := LayoutRef(GinkgoT().TempDir(), "copied")
 			src := RegistryRef(Host, ImageRepo, foobar.Tag)
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index a0c6cec55..b31b10e3e 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -547,6 +547,15 @@ var _ = Describe("OCI image layout users:", func() {
 		}
 		descriptor := "{\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"digest\":\"sha256:f20c43161d73848408ef247f0ec7111b19fe58ffebc0cbcaa0d2c8bda4967268\",\"size\":246}"
 
+		It("should fail to specify referrers garbage collection", func() {
+			manifestPath := WriteTempFile("manifest.json", manifest)
+			root := filepath.Dir(manifestPath)
+			ORAS("manifest", "push", Flags.Layout, manifestPath).
+				WithWorkDir(root).
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				ExpectFailure().Exec()
+		})
+
 		It("should push a manifest from stdin", func() {
 			root := GinkgoT().TempDir()
 			prepare(root)
@@ -555,6 +564,7 @@ var _ = Describe("OCI image layout users:", func() {
 				WithInput(strings.NewReader(manifest)).Exec()
 			validate(root, manifestDigest, "")
 		})
+
 		It("should push a manifest from stdin and tag", func() {
 			tag := "from-stdin"
 			root := GinkgoT().TempDir()

From c7fc74b8f89d769600803d366093581a79bd5bc2 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 29 May 2023 08:59:04 +0000
Subject: [PATCH 25/40] update deps

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 2 +-
 go.mod                                | 2 +-
 go.sum                                | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 7d883e1a1..152299a48 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -35,7 +35,7 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 // SetReferrersGC sets the referrers GC option for the passed-in target.
 func (opts *Referrers) SetReferrersGC(target any) error {
 	if repo, ok := target.(*remote.Repository); ok {
-		repo.ReferrersGC = opts.GC
+		repo.SkipReferrersGC = !opts.GC
 	} else if opts.GC {
 		return errors.New("referrers GC can only be enforced to registry targets")
 	}
diff --git a/go.mod b/go.mod
index f468f64b4..fe2998ad3 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/go.sum b/go.sum
index e1bc29c20..0f7b25407 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed h1:yIhtSuHvrHQHDiTfGSFt366Z3qDQe0kQoqlH3Uu3bbA=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=

From 84a954226e80ea29acc7658f3ac5e22c2b5c77eb Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 00:50:52 +0000
Subject: [PATCH 26/40] update dep

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/root/manifest/delete.go | 2 +-
 go.mod                           | 2 +-
 go.sum                           | 4 ++--
 test/e2e/go.mod                  | 2 +-
 test/e2e/go.sum                  | 4 ++--
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/cmd/oras/root/manifest/delete.go b/cmd/oras/root/manifest/delete.go
index ea3c0df74..dff2e8d87 100644
--- a/cmd/oras/root/manifest/delete.go
+++ b/cmd/oras/root/manifest/delete.go
@@ -82,7 +82,7 @@ func deleteManifest(ctx context.Context, opts deleteOptions) error {
 	if err != nil {
 		return err
 	}
-	repo.ReferrersGC = opts.GC
+	repo.SkipReferrersGC = !opts.GC
 
 	if repo.Reference.Reference == "" {
 		return oerrors.NewErrInvalidReference(repo.Reference)
diff --git a/go.mod b/go.mod
index fe2998ad3..889ad699a 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/go.sum b/go.sum
index 0f7b25407..f1bef059e 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed h1:yIhtSuHvrHQHDiTfGSFt366Z3qDQe0kQoqlH3Uu3bbA=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529082502-699eb38212ed/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index 5aa928fa9..d082c222c 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
 
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index 1a742e0bf..bc5048597 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,8 +24,8 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b h1:MoOGc1X5qRL+n4AtzaI9TgzLcsDbWSgU34/gVB1shQs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230526033205-9b4915420e0b/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=

From 0d3705dce1f2906ac7fe6d6964bc3bc763f07bfd Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 07:21:30 +0000
Subject: [PATCH 27/40] update

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/go.mod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index d082c222c..5df09c9cf 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
 
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7

From ce74b3437d8f6c903ee0769d371fafa37bf03d65 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 07:28:16 +0000
Subject: [PATCH 28/40] update version

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 go.mod          | 2 +-
 test/e2e/go.sum | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/go.mod b/go.mod
index 889ad699a..21bf634c7 100644
--- a/go.mod
+++ b/go.mod
@@ -2,7 +2,7 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab
+replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
 
 require (
 	github.com/need-being/go-tree v0.1.0
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index bc5048597..f576b8fed 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,8 +24,8 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=

From 43f8b3ed4f3addc18e99fea05bdc5d4f34122ecc Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 07:43:10 +0000
Subject: [PATCH 29/40] mod tidy

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 go.sum | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/go.sum b/go.sum
index f1bef059e..e5b482fca 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,8 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab h1:31HbzcDB/huc5APa/EXqQYq1Wj08sAbTCAQTaZd8B+s=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529101657-1ebc3f4464ab/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
+github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=

From 96648431da7fa8b40f0bd10c749fdc12ae45a028 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 30 May 2023 08:03:13 +0000
Subject: [PATCH 30/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/manifest.go | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index b31b10e3e..5369f8e6e 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -550,10 +550,10 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
-			ORAS("manifest", "push", Flags.Layout, manifestPath).
+			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--referrers-gc").
 				WithWorkDir(root).
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
-				ExpectFailure().Exec()
+				ExpectFailure().
+				MatchContent("Error: referrers GC can only be enforced to registry targets\n").Exec()
 		})
 
 		It("should push a manifest from stdin", func() {

From a397824a60779c1915acd4918d53959cabf59eb4 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 1 Jun 2023 00:26:21 +0000
Subject: [PATCH 31/40] rename flag

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 8 ++++----
 cmd/oras/root/manifest/delete.go      | 2 +-
 go.mod                                | 4 +---
 go.sum                                | 6 ++++--
 test/e2e/go.mod                       | 4 +---
 test/e2e/go.sum                       | 4 ++--
 test/e2e/suite/command/attach.go      | 2 +-
 test/e2e/suite/command/cp.go          | 2 +-
 test/e2e/suite/command/manifest.go    | 2 +-
 9 files changed, 16 insertions(+), 18 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 152299a48..54cec6c6f 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -24,19 +24,19 @@ import (
 
 // Referrers option struct.
 type Referrers struct {
-	GC bool
+	SkipDeleteReferrers bool
 }
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
-	fs.BoolVarP(&opts.GC, "referrers-gc", "", false, "enforce garbage collection when referrers API is not supported")
+	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", false, "skip deleting old referrers index, only work on registry when referrers API is not supported")
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.
 func (opts *Referrers) SetReferrersGC(target any) error {
 	if repo, ok := target.(*remote.Repository); ok {
-		repo.SkipReferrersGC = !opts.GC
-	} else if opts.GC {
+		repo.SkipReferrersGC = opts.SkipDeleteReferrers
+	} else if opts.SkipDeleteReferrers {
 		return errors.New("referrers GC can only be enforced to registry targets")
 	}
 	return nil
diff --git a/cmd/oras/root/manifest/delete.go b/cmd/oras/root/manifest/delete.go
index dff2e8d87..d347d2b2c 100644
--- a/cmd/oras/root/manifest/delete.go
+++ b/cmd/oras/root/manifest/delete.go
@@ -82,7 +82,7 @@ func deleteManifest(ctx context.Context, opts deleteOptions) error {
 	if err != nil {
 		return err
 	}
-	repo.SkipReferrersGC = !opts.GC
+	repo.SkipReferrersGC = opts.SkipDeleteReferrers
 
 	if repo.Reference.Reference == "" {
 		return oerrors.NewErrInvalidReference(repo.Reference)
diff --git a/go.mod b/go.mod
index 21bf634c7..fabcdff52 100644
--- a/go.mod
+++ b/go.mod
@@ -2,8 +2,6 @@ module oras.land/oras
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
-
 require (
 	github.com/need-being/go-tree v0.1.0
 	github.com/opencontainers/go-digest v1.0.0
@@ -14,7 +12,7 @@ require (
 	github.com/spf13/pflag v1.0.5
 	golang.org/x/term v0.8.0
 	gopkg.in/yaml.v3 v3.0.1
-	oras.land/oras-go/v2 v2.2.0
+	oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6
 )
 
 require (
diff --git a/go.sum b/go.sum
index e5b482fca..7814d36a9 100644
--- a/go.sum
+++ b/go.sum
@@ -16,8 +16,6 @@ github.com/oras-project/oras-credentials-go v0.1.1 h1:9EHrcJ1LcC7N9w2rfB9n8c1be+
 github.com/oras-project/oras-credentials-go v0.1.1/go.mod h1:188MBZBQQbrLlrOZY37hc8Z4Xjl+wP3PaIJkJuk94JM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
@@ -40,3 +38,7 @@ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+oras.land/oras-go/v2 v2.2.0 h1:E1fqITD56Eg5neZbxBtAdZVgDHD6wBabJo6xESTcQyo=
+oras.land/oras-go/v2 v2.2.0/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6 h1:2P1fjq1znGLo7tjy9PJsZrFF5L+qywbv28IgzKEX62E=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
diff --git a/test/e2e/go.mod b/test/e2e/go.mod
index 5df09c9cf..d31b3591a 100644
--- a/test/e2e/go.mod
+++ b/test/e2e/go.mod
@@ -2,15 +2,13 @@ module oras.land/oras/test/e2e
 
 go 1.20
 
-replace oras.land/oras-go/v2 => github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75
-
 require (
 	github.com/onsi/ginkgo/v2 v2.9.7
 	github.com/onsi/gomega v1.27.7
 	github.com/opencontainers/go-digest v1.0.0
 	github.com/opencontainers/image-spec v1.1.0-rc.3
 	gopkg.in/yaml.v2 v2.4.0
-	oras.land/oras-go/v2 v2.2.0
+	oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6
 )
 
 require (
diff --git a/test/e2e/go.sum b/test/e2e/go.sum
index f576b8fed..7d79a95e7 100644
--- a/test/e2e/go.sum
+++ b/test/e2e/go.sum
@@ -24,8 +24,6 @@ github.com/opencontainers/image-spec v1.1.0-rc.3 h1:GT9Xon8YrLxz6N7sErbN81V8J4lO
 github.com/opencontainers/image-spec v1.1.0-rc.3/go.mod h1:X4pATf0uXsnn3g5aiGIsVnJBR4mxhKzfwmvK/B2NTm8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75 h1:kMGjc8rYeWaipvK4SHawreg40cr5v67U8HDVi1rXbDs=
-github.com/qweeah/oras-go/v2 v2.0.0-20230529235543-a9c210426e75/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY=
@@ -49,3 +47,5 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6 h1:2P1fjq1znGLo7tjy9PJsZrFF5L+qywbv28IgzKEX62E=
+oras.land/oras-go/v2 v2.2.1-0.20230531090906-7dd0378382c6/go.mod h1:pXjn0+KfarspMHHNR3A56j3tgvr+mxArHuI8qVn59v8=
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 9d053f9b4..e7ee5bdae 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -208,7 +208,7 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
-			ORAS("attach", "--artifact-type", "test.attach", "--referrers-gc", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
 				ExpectFailure().
 				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
 				Exec()
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 0f0a51911..bd8dd883e 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -324,7 +324,7 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
 		It("should fail to specify referrers garbage collection", func() {
-			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--referrers-gc").
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers").
 				ExpectFailure().
 				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
 				Exec()
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 5369f8e6e..600a6676b 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -550,7 +550,7 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
-			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--referrers-gc").
+			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers").
 				WithWorkDir(root).
 				ExpectFailure().
 				MatchContent("Error: referrers GC can only be enforced to registry targets\n").Exec()

From 7984217290bc33a369d8d6cab291f806e2cc07ce Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Fri, 2 Jun 2023 10:21:30 +0000
Subject: [PATCH 32/40] fix: default to true

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 54cec6c6f..09da031df 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -29,7 +29,7 @@ type Referrers struct {
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
-	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", false, "skip deleting old referrers index, only work on registry when referrers API is not supported")
+	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", true, "skip deleting old referrers index, only work on registry when referrers API is not supported")
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.

From cd95fa1980a8bb7ed11a291bebc1d570a9b96573 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Fri, 2 Jun 2023 10:30:32 +0000
Subject: [PATCH 33/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 4 ++--
 test/e2e/suite/command/attach.go      | 4 ++--
 test/e2e/suite/command/cp.go          | 4 ++--
 test/e2e/suite/command/manifest.go    | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 09da031df..40074c1ee 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -36,8 +36,8 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 func (opts *Referrers) SetReferrersGC(target any) error {
 	if repo, ok := target.(*remote.Repository); ok {
 		repo.SkipReferrersGC = opts.SkipDeleteReferrers
-	} else if opts.SkipDeleteReferrers {
-		return errors.New("referrers GC can only be enforced to registry targets")
+	} else if !opts.SkipDeleteReferrers {
+		return errors.New("referrers deletion can only be enforced upon registry targets")
 	}
 	return nil
 }
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index e7ee5bdae..b36c7e9d5 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -208,9 +208,9 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
-			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers=false", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
 				ExpectFailure().
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
 				Exec()
 		})
 
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index bd8dd883e..161782d23 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -324,9 +324,9 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
 		It("should fail to specify referrers garbage collection", func() {
-			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers").
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers=false").
 				ExpectFailure().
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").
+				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
 				Exec()
 		})
 		It("should copy an image from a registry to an OCI image layout via tag", func() {
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 600a6676b..e190d2cd0 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -550,10 +550,10 @@ var _ = Describe("OCI image layout users:", func() {
 		It("should fail to specify referrers garbage collection", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
-			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers").
+			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers=false").
 				WithWorkDir(root).
 				ExpectFailure().
-				MatchContent("Error: referrers GC can only be enforced to registry targets\n").Exec()
+				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").Exec()
 		})
 
 		It("should push a manifest from stdin", func() {

From da916918d583e2fc9b989ea1d805afffad48486b Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 00:52:02 +0000
Subject: [PATCH 34/40] change default value to false

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 40074c1ee..d9b16a431 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -29,7 +29,7 @@ type Referrers struct {
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
-	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", true, "skip deleting old referrers index, only work on registry when referrers API is not supported")
+	fs.BoolVarP(&opts.SkipDeleteReferrers, "skip-delete-referrers", "", false, "skip deleting old referrers index, only work on registry when referrers API is not supported")
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.

From b302cdb09a49a8906593fc02dcc525d7449fe732 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 01:31:38 +0000
Subject: [PATCH 35/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go |  8 +++-----
 cmd/oras/root/attach.go               |  6 ++----
 cmd/oras/root/cp.go                   |  6 ++----
 cmd/oras/root/manifest/push.go        |  6 ++----
 test/e2e/suite/command/attach.go      | 18 +++++++++---------
 test/e2e/suite/command/cp.go          | 12 ++++++------
 test/e2e/suite/command/manifest.go    |  6 +++---
 7 files changed, 27 insertions(+), 35 deletions(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index d9b16a431..9284788a3 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -16,8 +16,7 @@ limitations under the License.
 package option
 
 import (
-	"errors"
-
+	"github.com/sirupsen/logrus"
 	"github.com/spf13/pflag"
 	"oras.land/oras-go/v2/registry/remote"
 )
@@ -33,11 +32,10 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 }
 
 // SetReferrersGC sets the referrers GC option for the passed-in target.
-func (opts *Referrers) SetReferrersGC(target any) error {
+func (opts *Referrers) SetReferrersGC(target any, logger logrus.FieldLogger) {
 	if repo, ok := target.(*remote.Repository); ok {
 		repo.SkipReferrersGC = opts.SkipDeleteReferrers
 	} else if !opts.SkipDeleteReferrers {
-		return errors.New("referrers deletion can only be enforced upon registry targets")
+		logger.Warnln("referrers deletion can only be enforced upon registry")
 	}
-	return nil
 }
diff --git a/cmd/oras/root/attach.go b/cmd/oras/root/attach.go
index 9de992440..69d4f7f6b 100644
--- a/cmd/oras/root/attach.go
+++ b/cmd/oras/root/attach.go
@@ -99,7 +99,7 @@ Example - Attach file to the manifest tagged 'v1' in an OCI layout folder 'layou
 }
 
 func runAttach(ctx context.Context, opts attachOptions) error {
-	ctx, _ = opts.WithContext(ctx)
+	ctx, logger := opts.WithContext(ctx)
 	annotations, err := opts.LoadManifestAnnotations()
 	if err != nil {
 		return err
@@ -123,9 +123,7 @@ func runAttach(ctx context.Context, opts attachOptions) error {
 	if err := opts.EnsureReferenceNotEmpty(); err != nil {
 		return err
 	}
-	if err = opts.SetReferrersGC(dst); err != nil {
-		return err
-	}
+	opts.SetReferrersGC(dst, logger)
 
 	subject, err := dst.Resolve(ctx, opts.Reference)
 	if err != nil {
diff --git a/cmd/oras/root/cp.go b/cmd/oras/root/cp.go
index 5a1a07a24..5e0982625 100644
--- a/cmd/oras/root/cp.go
+++ b/cmd/oras/root/cp.go
@@ -97,7 +97,7 @@ Example - Copy an artifact with multiple tags with concurrency tuned:
 }
 
 func runCopy(ctx context.Context, opts copyOptions) error {
-	ctx, _ = opts.WithContext(ctx)
+	ctx, logger := opts.WithContext(ctx)
 
 	// Prepare source
 	src, err := opts.From.NewReadonlyTarget(ctx, opts.Common)
@@ -113,9 +113,7 @@ func runCopy(ctx context.Context, opts copyOptions) error {
 	if err != nil {
 		return err
 	}
-	if err = opts.SetReferrersGC(dst); err != nil {
-		return err
-	}
+	opts.SetReferrersGC(dst, logger)
 
 	// Prepare copy options
 	committed := &sync.Map{}
diff --git a/cmd/oras/root/manifest/push.go b/cmd/oras/root/manifest/push.go
index c0b115420..1d3e8ce08 100644
--- a/cmd/oras/root/manifest/push.go
+++ b/cmd/oras/root/manifest/push.go
@@ -105,16 +105,14 @@ Example - Push a manifest to an OCI layout folder 'layout-dir' and tag with 'v1'
 }
 
 func pushManifest(ctx context.Context, opts pushOptions) error {
-	ctx, _ = opts.WithContext(ctx)
+	ctx, logger := opts.WithContext(ctx)
 	var target oras.Target
 	var err error
 	target, err = opts.NewTarget(opts.Common)
 	if err != nil {
 		return err
 	}
-	if err = opts.SetReferrersGC(target); err != nil {
-		return err
-	}
+	opts.SetReferrersGC(target, logger)
 	if repo, ok := target.(*remote.Repository); ok {
 		target = repo.Manifests()
 	}
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index b36c7e9d5..9896acd56 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -205,15 +205,6 @@ var _ = Describe("OCI image layout users:", func() {
 			ORAS("cp", RegistryRef(Host, ImageRepo, foobar.Tag), Flags.ToLayout, LayoutRef(root, foobar.Tag)).Exec()
 		}
 
-		It("should fail to specify referrers garbage collection", func() {
-			root := PrepareTempFiles()
-			subjectRef := LayoutRef(root, foobar.Tag)
-			ORAS("attach", "--artifact-type", "test.attach", "--skip-delete-referrers=false", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
-				ExpectFailure().
-				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
-				Exec()
-		})
-
 		It("should attach a file to a subject", func() {
 			root := PrepareTempFiles()
 			subjectRef := LayoutRef(root, foobar.Tag)
@@ -223,6 +214,15 @@ var _ = Describe("OCI image layout users:", func() {
 				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
 		})
 
+		It("should attach and output warning for referrers deletion by default", func() {
+			root := PrepareTempFiles()
+			subjectRef := LayoutRef(root, foobar.Tag)
+			prepare(root)
+			ORAS("attach", "--artifact-type", "test.attach", "-v", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				MatchContent("Error: referrers deletion can only be enforced upon registry\n").
+				Exec()
+		})
+
 		It("should attach a file to a subject and export the built manifest", func() {
 			// prepare
 			root := PrepareTempFiles()
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index 161782d23..d5decaa3f 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -323,12 +323,6 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 
 var _ = Describe("OCI layout users:", func() {
 	When("running `cp`", func() {
-		It("should fail to specify referrers garbage collection", func() {
-			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "--skip-delete-referrers=false").
-				ExpectFailure().
-				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").
-				Exec()
-		})
 		It("should copy an image from a registry to an OCI image layout via tag", func() {
 			dst := LayoutRef(GinkgoT().TempDir(), "copied")
 			src := RegistryRef(Host, ImageRepo, foobar.Tag)
@@ -339,6 +333,12 @@ var _ = Describe("OCI layout users:", func() {
 			Expect(srcManifest).To(Equal(dstManifest))
 		})
 
+		It("should copy and output verbosed warning for Feferrers deletion by default", func() {
+			ORAS("cp", RegistryRef(Host, ArtifactRepo, foobar.Tag), GinkgoT().TempDir(), Flags.ToLayout, "-v").
+				MatchErrKeyWords("referrers deletion can only be enforced upon registry\n").
+				Exec()
+		})
+
 		It("should copy an image from an OCI image layout to a registry via tag", func() {
 			layoutDir := GinkgoT().TempDir()
 			src := LayoutRef(layoutDir, "copied")
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index e190d2cd0..9cf86543c 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -547,13 +547,13 @@ var _ = Describe("OCI image layout users:", func() {
 		}
 		descriptor := "{\"mediaType\":\"application/vnd.oci.image.manifest.v1+json\",\"digest\":\"sha256:f20c43161d73848408ef247f0ec7111b19fe58ffebc0cbcaa0d2c8bda4967268\",\"size\":246}"
 
-		It("should fail to specify referrers garbage collection", func() {
+		It("should push and output verbosed warning for Feferrers deletion by default", func() {
 			manifestPath := WriteTempFile("manifest.json", manifest)
 			root := filepath.Dir(manifestPath)
+			prepare(root)
 			ORAS("manifest", "push", root, Flags.Layout, manifestPath, "--skip-delete-referrers=false").
 				WithWorkDir(root).
-				ExpectFailure().
-				MatchContent("Error: referrers deletion can only be enforced upon registry targets\n").Exec()
+				MatchErrKeyWords("referrers deletion can only be enforced upon registry\n").Exec()
 		})
 
 		It("should push a manifest from stdin", func() {

From e6980886c81e0ae908b0a605ffb0ee406033d0a0 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 01:40:08 +0000
Subject: [PATCH 36/40] fix e2e

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/suite/command/attach.go | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 9896acd56..1878bfea2 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -219,7 +219,8 @@ var _ = Describe("OCI image layout users:", func() {
 			subjectRef := LayoutRef(root, foobar.Tag)
 			prepare(root)
 			ORAS("attach", "--artifact-type", "test.attach", "-v", Flags.Layout, subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
-				MatchContent("Error: referrers deletion can only be enforced upon registry\n").
+				MatchErrKeyWords("referrers deletion can only be enforced upon registry\n").
+				WithWorkDir(root).
 				Exec()
 		})
 

From 785e8b97a9da06ac29b21306c291afd11d2427e5 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Tue, 6 Jun 2023 14:50:52 +0000
Subject: [PATCH 37/40] test: add e2e for referrers GC

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 test/e2e/README.md                         |  2 +-
 test/e2e/internal/testdata/foobar/const.go |  4 ++
 test/e2e/scripts/common.sh                 |  5 ++-
 test/e2e/scripts/e2e.sh                    |  6 ++-
 test/e2e/suite/command/attach.go           | 49 +++++++++++++++++++++-
 test/e2e/suite/command/cp.go               | 30 +++++++++++++
 test/e2e/suite/command/manifest.go         | 39 ++++++++++++++++-
 7 files changed, 127 insertions(+), 8 deletions(-)

diff --git a/test/e2e/README.md b/test/e2e/README.md
index 26e7332a8..f3fa24672 100644
--- a/test/e2e/README.md
+++ b/test/e2e/README.md
@@ -30,7 +30,7 @@ go test oras.land/oras/test/e2e/suite/${suite_name}
 This is super handy when you want to do step-by-step debugging from command-line or via an IDE. If you need to debug certain specs, use [focused specs](https://onsi.github.io/ginkgo/#focused-specs) but don't check it in.
 
 ### 4. Testing Registry Services
-The backend of E2E tests are two registry services: [oras-distribution](https://github.com/oras-project/distribution) and [upstream distribution](https://github.com/distribution/distribution). The former is expected to support image and artifact media types and referrer API; The latter is expected to only support image media type with subject and provide referrers via [tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema). 
+The backend of E2E tests are two registry services: [oras-distribution](https://github.com/oras-project/distribution) and [upstream distribution](https://github.com/distribution/distribution). The former is expected to support image and artifact media types and referrer API; The latter is expected to only support image media type with subject and provide referrers via [tag schema](https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#referrers-tag-schema), with deletion disabled. 
 
 You can run scenario test suite against your own registry services via setting `ORAS_REGISTRY_HOST` or `ORAS_REGISTRY_FALLBACK_HOST` environmental variables.
 
diff --git a/test/e2e/internal/testdata/foobar/const.go b/test/e2e/internal/testdata/foobar/const.go
index 0ea5471f0..66a0591f8 100644
--- a/test/e2e/internal/testdata/foobar/const.go
+++ b/test/e2e/internal/testdata/foobar/const.go
@@ -16,6 +16,8 @@ limitations under the License.
 package foobar
 
 import (
+	"fmt"
+
 	"github.com/opencontainers/go-digest"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"oras.land/oras/test/e2e/internal/utils/match"
@@ -24,6 +26,8 @@ import (
 var (
 	Tag              = "foobar"
 	Digest           = "sha256:fd6ed2f36b5465244d5dc86cb4e7df0ab8a9d24adc57825099f522fe009a22bb"
+	Size             = 851
+	DescriptorStr    = fmt.Sprintf(`{"mediaType":"application/vnd.oci.image.manifest.v1+json","digest":"%s","size":%d}`, Digest, Size)
 	ManifestStateKey = match.StateKey{Digest: "fd6ed2f36b54", Name: "application/vnd.oci.image.manifest.v1+json"}
 
 	FileLayerNames = []string{
diff --git a/test/e2e/scripts/common.sh b/test/e2e/scripts/common.sh
index 7760a6578..e1d40f919 100755
--- a/test/e2e/scripts/common.sh
+++ b/test/e2e/scripts/common.sh
@@ -15,13 +15,14 @@
 
 help () {
     echo "Usage"
-    echo "  run-registry <mount-root> <image-name> <container-name> <container-port>"
+    echo "  run-registry <mount-root> <image-name> <container-name> <container-port> <deletion-enabled>"
     echo ""
     echo "Arguments"
     echo "  mount-root       root mounting directory for pre-baked registry storage files."
     echo "  image-name       image name of the registry."
     echo "  container-name   container name of the registry service."
     echo "  container-port   port to export the registry service."
+    echo "  delete-enabled   if set to true, the registry service will be configured to allow deletion."
 }
 
 # run registry service for testing
@@ -61,7 +62,7 @@ run_registry () {
     try_clean_up $ctr_name
     docker run --pull always -d -p $ctr_port:5000 --rm --name $ctr_name \
         -u $(id -u $(whoami)) \
-        --env REGISTRY_STORAGE_DELETE_ENABLED=true \
+        --env REGISTRY_STORAGE_DELETE_ENABLED=$5 \
         --env REGISTRY_AUTH_HTPASSWD_REALM=test-basic \
         --env REGISTRY_AUTH_HTPASSWD_PATH=/etc/docker/registry/passwd \
         --mount type=bind,source=$mnt_root/docker,target=/var/lib/registry/docker \
diff --git a/test/e2e/scripts/e2e.sh b/test/e2e/scripts/e2e.sh
index b110e38c6..08d555a77 100755
--- a/test/e2e/scripts/e2e.sh
+++ b/test/e2e/scripts/e2e.sh
@@ -49,14 +49,16 @@ run_registry \
   ${e2e_root}/testdata/distribution/mount \
   ghcr.io/oras-project/registry:v1.0.0-rc.4 \
   $oras_container_name \
-  $ORAS_REGISTRY_PORT
+  $ORAS_REGISTRY_PORT \
+  true
 
 echo " === preparing upstream distribution === "
 run_registry \
   ${e2e_root}/testdata/distribution/mount_fallback \
   registry:2.8.1 \
   $upstream_container_name \
-  $ORAS_REGISTRY_FALLBACK_PORT
+  $ORAS_REGISTRY_FALLBACK_PORT \
+  false
 
 echo " === run tests === "
 if ! ginkgo -r -p --succinct suite; then 
diff --git a/test/e2e/suite/command/attach.go b/test/e2e/suite/command/attach.go
index 1878bfea2..1410bbed6 100644
--- a/test/e2e/suite/command/attach.go
+++ b/test/e2e/suite/command/attach.go
@@ -167,7 +167,25 @@ var _ = Describe("Fallback registry users:", func() {
 			subjectRef := RegistryRef(FallbackHost, testRepo, foobar.Tag)
 			prepare(RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), subjectRef)
 			// test
-			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), "--image-spec", "v1.1-image").
+			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				WithWorkDir(tempDir).
+				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
+
+			// validate
+			var index ocispec.Index
+			bytes := ORAS("discover", subjectRef, "-o", "json").Exec().Out.Contents()
+			Expect(json.Unmarshal(bytes, &index)).ShouldNot(HaveOccurred())
+			Expect(len(index.Manifests)).To(Equal(1))
+			Expect(index.Manifests[0].MediaType).To(Equal(ocispec.MediaTypeImageManifest))
+		})
+
+		It("should fail to attach again when cleaning referrers index", func() {
+			testRepo := attachTestRepo("fallback/fail-gc")
+			tempDir := PrepareTempFiles()
+			subjectRef := RegistryRef(FallbackHost, testRepo, foobar.Tag)
+			prepare(RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), subjectRef)
+			// test
+			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
 				WithWorkDir(tempDir).
 				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
 
@@ -177,6 +195,35 @@ var _ = Describe("Fallback registry users:", func() {
 			Expect(json.Unmarshal(bytes, &index)).ShouldNot(HaveOccurred())
 			Expect(len(index.Manifests)).To(Equal(1))
 			Expect(index.Manifests[0].MediaType).To(Equal(ocispec.MediaTypeImageManifest))
+			// test
+			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), "-a", "test.type=another.image").
+				WithWorkDir(tempDir).
+				MatchErrKeyWords("Error: failed to delete dangling referrers index").
+				ExpectFailure().Exec()
+		})
+
+		It("should attach again and skip cleanning index", func() {
+			testRepo := attachTestRepo("fallback/skip-gc")
+			tempDir := PrepareTempFiles()
+			subjectRef := RegistryRef(FallbackHost, testRepo, foobar.Tag)
+			prepare(RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), subjectRef)
+			// test
+			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				WithWorkDir(tempDir).
+				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
+			// validate
+			var index ocispec.Index
+			bytes := ORAS("discover", subjectRef, "-o", "json").Exec().Out.Contents()
+			Expect(json.Unmarshal(bytes, &index)).ShouldNot(HaveOccurred())
+			Expect(len(index.Manifests)).To(Equal(1))
+			// test
+			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia), "-a", "test.type=another.image", "--skip-delete-referrers").
+				WithWorkDir(tempDir).
+				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
+			// validate
+			bytes = ORAS("discover", subjectRef, "-o", "json").Exec().Out.Contents()
+			Expect(json.Unmarshal(bytes, &index)).ShouldNot(HaveOccurred())
+			Expect(len(index.Manifests)).To(Equal(2))
 		})
 
 		It("should attach a file via a OCI Image and generate referrer via tag schema", func() {
diff --git a/test/e2e/suite/command/cp.go b/test/e2e/suite/command/cp.go
index d5decaa3f..5865ba0cb 100644
--- a/test/e2e/suite/command/cp.go
+++ b/test/e2e/suite/command/cp.go
@@ -31,6 +31,7 @@ import (
 	"oras.land/oras/test/e2e/internal/testdata/foobar"
 	ma "oras.land/oras/test/e2e/internal/testdata/multi_arch"
 	. "oras.land/oras/test/e2e/internal/utils"
+	"oras.land/oras/test/e2e/internal/utils/match"
 )
 
 func cpTestRepo(text string) string {
@@ -245,6 +246,34 @@ var _ = Describe("Common registry users:", func() {
 
 var _ = Describe("OCI spec 1.0 registry users:", func() {
 	When("running `cp`", func() {
+		It("should fail to copy when cleaning referrers index", func() {
+			testRepo := cpTestRepo("fallback/fail-gc")
+			tempDir := PrepareTempFiles()
+			subjectRef := RegistryRef(FallbackHost, testRepo, foobar.Tag)
+			// prepare
+			prepare(RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), subjectRef)
+			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				WithWorkDir(tempDir).
+				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
+			// test
+			ORAS("cp", "-r", RegistryRef(FallbackHost, ArtifactRepo, foobar.FallbackSBOMImageReferrer.Digest.String()), RegistryRef(FallbackHost, testRepo, ""), "-v").
+				MatchErrKeyWords("Error: failed to delete dangling referrers index").
+				ExpectFailure().Exec()
+		})
+
+		It("should copy and skip cleaning referrers index", func() {
+			testRepo := cpTestRepo("fallback/skip-gc")
+			tempDir := PrepareTempFiles()
+			subjectRef := RegistryRef(FallbackHost, testRepo, foobar.Tag)
+			// prepare
+			prepare(RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), subjectRef)
+			ORAS("attach", "--artifact-type", "test.attach", subjectRef, fmt.Sprintf("%s:%s", foobar.AttachFileName, foobar.AttachFileMedia)).
+				WithWorkDir(tempDir).
+				MatchStatus([]match.StateKey{foobar.AttachFileStateKey}, false, 1).Exec()
+			// test
+			ORAS("cp", "-r", RegistryRef(FallbackHost, ArtifactRepo, foobar.FallbackSBOMImageReferrer.Digest.String()), RegistryRef(FallbackHost, testRepo, ""), "--skip-delete-referrers").Exec()
+		})
+
 		It("should copy an image artifact and its referrers from a registry to a fallback registry", func() {
 			repo := cpTestRepo("to-fallback")
 			stateKeys := append(append(foobarStates, foobar.ImageReferrersStateKeys...), foobar.ImageReferrerConfigStateKeys...)
@@ -255,6 +284,7 @@ var _ = Describe("OCI spec 1.0 registry users:", func() {
 			ORAS("discover", "-o", "tree", RegistryRef(FallbackHost, repo, foobar.Digest)).
 				WithDescription("discover referrer via subject").MatchKeyWords(foobar.SignatureImageReferrer.Digest.String(), foobar.SBOMImageReferrer.Digest.String()).Exec()
 		})
+
 		It("should copy an image artifact and its referrers from a fallback registry to a registry", func() {
 			repo := cpTestRepo("from-fallback")
 			stateKeys := append(append(foobarStates, foobar.FallbackImageReferrersStateKeys...), foobar.ImageReferrerConfigStateKeys...)
diff --git a/test/e2e/suite/command/manifest.go b/test/e2e/suite/command/manifest.go
index 9cf86543c..effd932e5 100644
--- a/test/e2e/suite/command/manifest.go
+++ b/test/e2e/suite/command/manifest.go
@@ -518,9 +518,7 @@ var _ = Describe("OCI image layout users:", func() {
 			ORAS("manifest", "fetch-config", Flags.Layout, root).ExpectFailure().MatchErrKeyWords("Error:", "invalid image reference").Exec()
 		})
 	})
-})
 
-var _ = Describe("OCI image layout users:", func() {
 	When("running `manifest push`", func() {
 		scratchSize := 2
 		scratchDigest := "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
@@ -616,3 +614,40 @@ var _ = Describe("OCI image layout users:", func() {
 		})
 	})
 })
+
+func pushTestRepo(text string) string {
+	return fmt.Sprintf("command/push/%d/%s", GinkgoRandomSeed(), text)
+}
+
+var _ = Describe("Fallback registry users:", func() {
+	When("running `manifest push`", func() {
+		manifest := fmt.Sprintf(`{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","config":{"mediaType":"oras.test","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2},"subject":%s,"layers":[]}`, foobar.DescriptorStr)
+		It("should fail to push manifest when cleaning referrers index", func() {
+			testRepo := pushTestRepo("fallback/fail-gc")
+			subjectRef := RegistryRef(FallbackHost, testRepo, foobar.Tag)
+			// prepare
+			ORAS("cp", RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), subjectRef, "-r").Exec()
+			// test
+			ORAS("manifest", "push", RegistryRef(FallbackHost, testRepo, ""), "-").
+				WithInput(strings.NewReader(manifest)).
+				ExpectFailure().
+				MatchErrKeyWords("failed to delete dangling referrers index").
+				Exec()
+		})
+		It("should push manifest and skip cleaning referrers index", func() {
+			testRepo := pushTestRepo("fallback/skip-gc")
+			subjectRef := RegistryRef(FallbackHost, testRepo, foobar.Tag)
+			// prepare
+			ORAS("cp", RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), subjectRef, "-r").Exec()
+			// test
+			ORAS("manifest", "push", RegistryRef(FallbackHost, testRepo, ""), "-", "--skip-delete-referrers").
+				WithInput(strings.NewReader(manifest)).
+				Exec()
+			// validate
+			var index ocispec.Index
+			bytes := ORAS("discover", subjectRef, "-o", "json").Exec().Out.Contents()
+			Expect(json.Unmarshal(bytes, &index)).ShouldNot(HaveOccurred())
+			Expect(len(index.Manifests)).To(Equal(2))
+		})
+	})
+})

From 1084fa6b6d5b61a48f461b39091cd78e45206855 Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 8 Jun 2023 06:24:00 +0000
Subject: [PATCH 38/40] add error hint

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/errors/errors.go | 8 ++++++++
 cmd/oras/root/attach.go            | 5 +++++
 cmd/oras/root/cp.go                | 5 +++++
 cmd/oras/root/manifest/delete.go   | 2 --
 cmd/oras/root/manifest/push.go     | 4 ++++
 5 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/cmd/oras/internal/errors/errors.go b/cmd/oras/internal/errors/errors.go
index e3c6e4c43..631403ac6 100644
--- a/cmd/oras/internal/errors/errors.go
+++ b/cmd/oras/internal/errors/errors.go
@@ -16,9 +16,11 @@ limitations under the License.
 package errors
 
 import (
+	"errors"
 	"fmt"
 
 	"oras.land/oras-go/v2/registry"
+	"oras.land/oras-go/v2/registry/remote"
 )
 
 // NewErrInvalidReference creates a new error based on the reference string.
@@ -30,3 +32,9 @@ func NewErrInvalidReference(ref registry.Reference) error {
 func NewErrInvalidReferenceStr(ref string) error {
 	return fmt.Errorf("%s: invalid image reference, expecting <name:tag|name@digest>", ref)
 }
+
+// IsReferrersIndexDelete checks if err is a referrers index delete error.
+func IsReferrersIndexDelete(err error) bool {
+	var re *remote.ReferrersError
+	return errors.As(err, &re) && re.IsReferrersIndexDelete()
+}
diff --git a/cmd/oras/root/attach.go b/cmd/oras/root/attach.go
index 69d4f7f6b..3d0d07eee 100644
--- a/cmd/oras/root/attach.go
+++ b/cmd/oras/root/attach.go
@@ -19,6 +19,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"os"
 	"strings"
 
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
@@ -26,6 +27,7 @@ import (
 	"oras.land/oras-go/v2"
 	"oras.land/oras-go/v2/content"
 	"oras.land/oras-go/v2/content/file"
+	oerr "oras.land/oras/cmd/oras/internal/errors"
 	"oras.land/oras/cmd/oras/internal/option"
 	"oras.land/oras/internal/graph"
 )
@@ -167,6 +169,9 @@ func runAttach(ctx context.Context, opts attachOptions) error {
 
 	root, err := pushArtifact(dst, pack, copy)
 	if err != nil {
+		if oerr.IsReferrersIndexDelete(err) {
+			fmt.Fprintln(os.Stderr, "attached successfully but failed to remove the outdated referrers index, please use `--skip-delete-referrers` if you want to skip the deletion")
+		}
 		return err
 	}
 
diff --git a/cmd/oras/root/cp.go b/cmd/oras/root/cp.go
index 5e0982625..3128a63aa 100644
--- a/cmd/oras/root/cp.go
+++ b/cmd/oras/root/cp.go
@@ -18,6 +18,7 @@ package root
 import (
 	"context"
 	"fmt"
+	"os"
 	"strings"
 	"sync"
 
@@ -26,6 +27,7 @@ import (
 	"github.com/spf13/cobra"
 	"oras.land/oras-go/v2"
 	"oras.land/oras/cmd/oras/internal/display"
+	oerr "oras.land/oras/cmd/oras/internal/errors"
 	"oras.land/oras/cmd/oras/internal/option"
 	"oras.land/oras/internal/graph"
 )
@@ -169,6 +171,9 @@ func runCopy(ctx context.Context, opts copyOptions) error {
 		}
 	}
 	if err != nil {
+		if oerr.IsReferrersIndexDelete(err) {
+			fmt.Fprintln(os.Stderr, "failed to remove the outdated referrers index, please use `--skip-delete-referrers` if you want to skip the deletion")
+		}
 		return err
 	}
 
diff --git a/cmd/oras/root/manifest/delete.go b/cmd/oras/root/manifest/delete.go
index d347d2b2c..8ece10400 100644
--- a/cmd/oras/root/manifest/delete.go
+++ b/cmd/oras/root/manifest/delete.go
@@ -33,7 +33,6 @@ type deleteOptions struct {
 	option.Descriptor
 	option.Pretty
 	option.Remote
-	option.Referrers
 
 	targetRef string
 }
@@ -82,7 +81,6 @@ func deleteManifest(ctx context.Context, opts deleteOptions) error {
 	if err != nil {
 		return err
 	}
-	repo.SkipReferrersGC = opts.SkipDeleteReferrers
 
 	if repo.Reference.Reference == "" {
 		return oerrors.NewErrInvalidReference(repo.Reference)
diff --git a/cmd/oras/root/manifest/push.go b/cmd/oras/root/manifest/push.go
index 1d3e8ce08..fcc5b433a 100644
--- a/cmd/oras/root/manifest/push.go
+++ b/cmd/oras/root/manifest/push.go
@@ -29,6 +29,7 @@ import (
 	"oras.land/oras-go/v2/errdef"
 	"oras.land/oras-go/v2/registry/remote"
 	"oras.land/oras/cmd/oras/internal/display"
+	oerr "oras.land/oras/cmd/oras/internal/errors"
 	"oras.land/oras/cmd/oras/internal/option"
 	"oras.land/oras/internal/file"
 )
@@ -153,6 +154,9 @@ func pushManifest(ctx context.Context, opts pushOptions) error {
 			return err
 		}
 		if _, err := oras.TagBytes(ctx, target, mediaType, contentBytes, ref); err != nil {
+			if oerr.IsReferrersIndexDelete(err) {
+				fmt.Fprintln(os.Stderr, "pushed successfully but failed to remove the outdated referrers index, please use `--skip-delete-referrers` if you want to skip the deletion")
+			}
 			return err
 		}
 		if err = display.PrintStatus(desc, "Uploaded ", verbose); err != nil {

From 6b92395e2c750a309e65d53fb34450afa252410e Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Thu, 29 Jun 2023 15:30:43 +0000
Subject: [PATCH 39/40] bug fix

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index 9284788a3..b6749dea7 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -35,7 +35,9 @@ func (opts *Referrers) ApplyFlags(fs *pflag.FlagSet) {
 func (opts *Referrers) SetReferrersGC(target any, logger logrus.FieldLogger) {
 	if repo, ok := target.(*remote.Repository); ok {
 		repo.SkipReferrersGC = opts.SkipDeleteReferrers
-	} else if !opts.SkipDeleteReferrers {
+	} else if opts.SkipDeleteReferrers {
+		// not a registry, can't skip referrers deletion
+		// TODO: change default value in 2.0
 		logger.Warnln("referrers deletion can only be enforced upon registry")
 	}
 }

From 757f2ae297b07173fb002870d4a146e72b03ff4f Mon Sep 17 00:00:00 2001
From: Billy Zha <jinzha1@microsoft.com>
Date: Mon, 3 Jul 2023 06:51:26 +0000
Subject: [PATCH 40/40] update comment

Signed-off-by: Billy Zha <jinzha1@microsoft.com>
---
 cmd/oras/internal/option/referrers.go | 1 -
 1 file changed, 1 deletion(-)

diff --git a/cmd/oras/internal/option/referrers.go b/cmd/oras/internal/option/referrers.go
index b6749dea7..4920c29d0 100644
--- a/cmd/oras/internal/option/referrers.go
+++ b/cmd/oras/internal/option/referrers.go
@@ -37,7 +37,6 @@ func (opts *Referrers) SetReferrersGC(target any, logger logrus.FieldLogger) {
 		repo.SkipReferrersGC = opts.SkipDeleteReferrers
 	} else if opts.SkipDeleteReferrers {
 		// not a registry, can't skip referrers deletion
-		// TODO: change default value in 2.0
 		logger.Warnln("referrers deletion can only be enforced upon registry")
 	}
 }