chore: backport main-branch fixes into release-1.2 branch

.github/workflows/release-github.yml

@@ -31,9 +31,9 @@ jobs:
         with:
           go-version: '1.23.4'
       - name: run goreleaser
-        uses: goreleaser/goreleaser-action@v5
+        uses: goreleaser/goreleaser-action@v6
         with:
-          version: latest
-          args: release --rm-dist
+          version: '~> v2'
+          args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.goreleaser.yml

@@ -14,6 +14,7 @@
 # To release:
 #   GITHUB_TOKEN=*** goreleaser
 
+version: 2
 builds:
 - main: ./cmd/oras
   binary: ./oras

README.md

@@ -15,7 +15,7 @@ the project website: [oras.land/cli](https://oras.land/docs/category/oras-comman
 
 ## Development Environment Setup
 
-Refer to the [development guide](https://oras.land/docs/community/developer_guide) to get started [contributing to ORAS](https://oras.land/docs/community/contributing_guide).
+Refer to the [development guide](https://oras.land/community/developer_guide) to get started [contributing to ORAS](https://oras.land/community/contributing_guide).
 
 ## Code of Conduct
 

cmd/oras/root/attach.go

@@ -55,7 +55,7 @@ func attachCmd() *cobra.Command {
 
 ** This command is in preview and under development. **
 
-Example - Attach file 'hi.txt' with aritifact type 'doc/example' to manifest 'hello:v1' in registry 'localhost:5000':
+Example - Attach file 'hi.txt' with artifact type 'doc/example' to manifest 'hello:v1' in registry 'localhost:5000':
   oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt
 
 Example - Attach file 'hi.txt' to a specific artifact with platform 'linux/amd64' in multi-arch index 'hello:v1'
@@ -77,6 +77,12 @@ Example - Attach an artifact with manifest annotations:
 Example - Attach file 'hi.txt' and add manifest annotations:
   oras attach --artifact-type doc/example --annotation "key=val" localhost:5000/hello:v1 hi.txt
 
+Example - Attach file 'hi.txt' and format output in JSON:
+  oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt --format json
+
+Example - Attach file 'hi.txt' and format output with Go template:
+  oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt --format go-template --template "{{.digest}}"
+
 Example - Attach file 'hi.txt' and export the pushed manifest to 'manifest.json':
   oras attach --artifact-type doc/example --export-manifest manifest.json localhost:5000/hello:v1 hi.txt
 

cmd/oras/root/cp.go

@@ -58,7 +58,7 @@ func copyCmd() *cobra.Command {
 		Use:     "cp [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]",
 		Aliases: []string{"copy"},
 		Short:   "Copy artifacts from one target to another",
-		Long: `Copy artifacts from one target to another
+		Long: `Copy artifacts from one target to another. When copying an image index, all of its manifests will be copied
 
 Example - Copy an artifact between registries:
   oras cp localhost:5000/net-monitor:v1 localhost:6000/net-monitor-copy:v1

cmd/oras/root/discover.go

@@ -51,27 +51,29 @@ func discoverCmd() *cobra.Command {
 
 ** This command is in preview and under development. **
 
-Example - Discover direct referrers of manifest 'hello:v1' in registry 'localhost:5000':
+Example - Discover referrers of manifest 'hello:v1' in registry 'localhost:5000', displayed in a tree view:
   oras discover localhost:5000/hello:v1
 
-Example - Discover direct referrers via referrers API:
+Example - Discover referrers via referrers API:
   oras discover --distribution-spec v1.1-referrers-api localhost:5000/hello:v1
 
-Example - Discover direct referrers via tag scheme:
+Example - Discover referrers via tag scheme:
   oras discover --distribution-spec v1.1-referrers-tag localhost:5000/hello:v1
 
-Example - Discover all the referrers of manifest 'hello:v1' in registry 'localhost:5000', displayed in a tree view:
-  oras discover -o tree localhost:5000/hello:v1
+Example - Discover referrers and display in a table view:
+  oras discover localhost:5000/hello:v1 --format table
+
+Example - Discover referrers and format output with Go template:
+  oras discover localhost:5000/hello:v1 --format go-template --template "{{.manifests}}"
 
 Example - Discover all the referrers of manifest with annotations, displayed in a tree view:
-  oras discover -v -o tree localhost:5000/hello:v1
+  oras discover -v localhost:5000/hello:v1
 
 Example - Discover referrers with type 'test-artifact' of manifest 'hello:v1' in registry 'localhost:5000':
   oras discover --artifact-type test-artifact localhost:5000/hello:v1
 
 Example - Discover referrers of the manifest tagged 'v1' in an OCI image layout folder 'layout-dir':
   oras discover --oci-layout layout-dir:v1
-  oras discover --oci-layout -v -o tree layout-dir:v1
 `,
 		Args: oerrors.CheckArgs(argument.Exactly(1), "the target artifact to discover referrers from"),
 		PreRunE: func(cmd *cobra.Command, args []string) error {

cmd/oras/root/manifest/fetch.go

@@ -55,6 +55,12 @@ Example - Fetch raw manifest from a registry:
 Example - Fetch the descriptor of a manifest from a registry:
   oras manifest fetch --descriptor localhost:5000/hello:v1
 
+Example - Fetch the manifest digest from a registry similar to the resolve command:
+  oras manifest fetch --format go-template --template '{{ .digest }}' localhost:5000/hello:v1
+
+Example - Fetch manifest and output metadata encoded in JSON:
+  oras manifest fetch localhost:5000/hello:v1 --format json
+
 Example - Fetch manifest from a registry with specified media type:
   oras manifest fetch --media-type 'application/vnd.oci.image.manifest.v1+json' localhost:5000/hello:v1
 

cmd/oras/root/pull.go

@@ -82,6 +82,12 @@ Example - Pull files from a registry with certain platform:
 Example - Pull all files with concurrency level tuned:
   oras pull --concurrency 6 localhost:5000/hello:v1
 
+Example - Pull files and format output in JSON:
+  oras pull localhost:5000/hello:v1 --format json
+
+Example - Pull files and format output with Go template:
+  oras pull localhost:5000/hello:v1 --format go-template="{{.reference}}"
+
 Example - Pull artifact files from an OCI image layout folder 'layout-dir':
   oras pull --oci-layout layout-dir:v1
 

cmd/oras/root/push.go

@@ -70,6 +70,9 @@ Example - Push file "hi.txt" with the custom media type "application/vnd.me.hi":
 Example - Push multiple files with different media types:
   oras push localhost:5000/hello:v1 hi.txt:application/vnd.me.hi bye.txt:application/vnd.me.bye
 
+Example - Push file with colon in name "hi:txt" with the default media type:
+  oras push localhost:5000/hello:v1 hi:txt:
+
 Example - Push file "hi.txt" with artifact type "application/vnd.example+type":
   oras push --artifact-type application/vnd.example+type localhost:5000/hello:v1 hi.txt
 
@@ -79,6 +82,12 @@ Example - Push file "hi.txt" with config type "application/vnd.me.config":
 Example - Push file "hi.txt" with the custom manifest config "config.json" of the custom media type "application/vnd.me.config":
   oras push --config config.json:application/vnd.me.config localhost:5000/hello:v1 hi.txt
 
+Example - Push file "hi.txt" and format output in JSON:
+  oras push localhost:5000/hello:v1 hi.txt --format json
+
+Example - Push file "hi.txt" and format output with Go template:
+  oras push localhost:5000/hello:v1 hi.txt --format go-template="{{.digest}}"
+
 Example - Push file to the insecure registry:
   oras push --insecure localhost:5000/hello:v1 hi.txt
 

cmd/oras/root/repo/tags.go

@@ -47,7 +47,7 @@ Example - Show tags of the target repository:
   oras repo tags localhost:5000/hello
 
 Example - Show tags in the target repository with digest-like tags hidden:
-  oras repo tags --exclude-digest-tag localhost:5000/hello
+  oras repo tags --exclude-digest-tags localhost:5000/hello
 
 Example - Show tags of the target repository that include values lexically after last:
   oras repo tags --last "last_tag" localhost:5000/hello

cmd/oras/root/tag.go

@@ -22,6 +22,7 @@ import (
 	"github.com/spf13/cobra"
 	"oras.land/oras-go/v2"
 	"oras.land/oras-go/v2/errdef"
+	"oras.land/oras-go/v2/registry/remote"
 	"oras.land/oras/cmd/oras/internal/argument"
 	"oras.land/oras/cmd/oras/internal/command"
 	"oras.land/oras/cmd/oras/internal/display/status"
@@ -57,7 +58,7 @@ Example - Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.1', 'v1.0
   oras tag --concurrency 1 localhost:5000/hello:v1.0.1 v1.0.2 latest
 
 Example - Tag the manifest 'v1.0.1' to 'v1.0.2' in an OCI image layout folder 'layout-dir':
-  oras tag layout-dir:v1.0.1 v1.0.2
+  oras tag --oci-layout layout-dir:v1.0.1 v1.0.2
 `,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 && (args[0] == "list" || args[0] == "ls") {
@@ -102,6 +103,11 @@ func tagManifest(cmd *cobra.Command, opts *tagOptions) error {
 	if err != nil {
 		return err
 	}
+	if targetRepo, ok := target.(*remote.Repository); ok {
+		// Since referrer capability has not been set or detected yet,
+		// nil is the only returned value and thus can be ignored
+		_ = targetRepo.SetReferrersCapability(true)
+	}
 	if err := opts.EnsureReferenceNotEmpty(cmd, true); err != nil {
 		return err
 	}

test/e2e/suite/command/tag.go

@@ -19,10 +19,12 @@ import (
 	"fmt"
 	"path/filepath"
 	"regexp"
+	"strings"
 
 	. "github.com/onsi/ginkgo/v2"
 	"github.com/onsi/gomega"
 	"github.com/onsi/gomega/gbytes"
+	"oras.land/oras/test/e2e/internal/testdata/foobar"
 	"oras.land/oras/test/e2e/internal/testdata/multi_arch"
 	. "oras.land/oras/test/e2e/internal/utils"
 )
@@ -56,14 +58,15 @@ var _ = Describe("ORAS beginners:", func() {
 	})
 })
 
+func tagAndValidate(reg string, repo string, tagOrDigest string, digestText string, tags ...string) {
+	out := ORAS(append([]string{"tag", RegistryRef(reg, repo, tagOrDigest)}, tags...)...).MatchKeyWords(tags...).Exec().Out
+	hint := regexp.QuoteMeta(fmt.Sprintf("Tagging [registry] %s", RegistryRef(reg, repo, digestText)))
+	gomega.Expect(out).To(gbytes.Say(hint))
+	gomega.Expect(out).NotTo(gbytes.Say(hint)) // should only say hint once
+	ORAS("repo", "tags", RegistryRef(reg, repo, "")).MatchKeyWords(tags...).Exec()
+}
+
 var _ = Describe("1.1 registry users:", func() {
-	var tagAndValidate = func(reg string, repo string, tagOrDigest string, digest string, tags ...string) {
-		out := ORAS(append([]string{"tag", RegistryRef(reg, repo, tagOrDigest)}, tags...)...).MatchKeyWords(tags...).Exec().Out
-		hint := regexp.QuoteMeta(fmt.Sprintf("Tagging [registry] %s", RegistryRef(reg, repo, digest)))
-		gomega.Expect(out).To(gbytes.Say(hint))
-		gomega.Expect(out).NotTo(gbytes.Say(hint)) // should only say hint once
-		ORAS("repo", "tags", RegistryRef(reg, repo, "")).MatchKeyWords(tags...).Exec()
-	}
 	When("running `tag`", func() {
 		It("should add a tag to an existent manifest when providing tag reference", func() {
 			tagAndValidate(ZOTHost, ImageRepo, multi_arch.Tag, multi_arch.Digest, "tag-via-tag")
@@ -77,6 +80,39 @@ var _ = Describe("1.1 registry users:", func() {
 		It("should add multiple tags to an existent manifest when providing tag reference", func() {
 			tagAndValidate(ZOTHost, ImageRepo, multi_arch.Tag, multi_arch.Digest, "tag1-via-tag", "tag1-via-tag", "tag1-via-tag")
 		})
+		It("should tag a referrer witout tag schema", func() {
+			// parepare:
+			repo := fmt.Sprintf("command/tag/%d/referrers", GinkgoRandomSeed())
+			ORAS("cp", "-r", RegistryRef(ZOTHost, ArtifactRepo, foobar.Tag), "--to-distribution-spec", "v1.1-referrers-api", RegistryRef(ZOTHost, repo, foobar.Tag)).Exec()
+			// test
+			referrerDigest := foobar.SBOMImageReferrer.Digest.String()
+			tagAndValidate(ZOTHost, repo, referrerDigest, referrerDigest, "tagged-referrer")
+			// ensure no referrer index is created
+			ref := RegistryRef(ZOTHost, repo, strings.Replace(foobar.Digest, ":", "-", 1))
+			ORAS("manifest", "fetch", ref).
+				MatchErrKeyWords(fmt.Sprintf("%s: not found", ref)).
+				ExpectFailure().
+				Exec()
+		})
+	})
+})
+
+var _ = Describe("1.0 registry users:", func() {
+	When("running `tag`", func() {
+		It("should tag a referrer witout tag schema", func() {
+			// prepare: copy to the fallback registry
+			repo := fmt.Sprintf("command/tag/%d/referrers", GinkgoRandomSeed())
+			ORAS("cp", "-r", RegistryRef(FallbackHost, ArtifactRepo, foobar.Tag), "--to-distribution-spec", "v1.1-referrers-api", RegistryRef(FallbackHost, repo, foobar.Tag)).Exec()
+			// test
+			referrerDigest := foobar.SBOMImageReferrer.Digest.String()
+			tagAndValidate(FallbackHost, repo, referrerDigest, referrerDigest, "tagged-referrer")
+			// ensure no referrer index is created
+			indexReferrerTag := RegistryRef(FallbackHost, repo, strings.Replace(foobar.Digest, ":", "-", 1))
+			ORAS("manifest", "fetch", indexReferrerTag).
+				MatchErrKeyWords(fmt.Sprintf("%s: not found", indexReferrerTag)).
+				ExpectFailure().
+				Exec()
+		})
 	})
 })