docs: add examples for --format (#1497)

Signed-off-by: Xiaoxuan Wang <[email protected]>

cmd/oras/root/attach.go

@@ -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/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

@@ -58,6 +58,9 @@ Example - Fetch the descriptor of a manifest from a registry:
 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

@@ -83,6 +83,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

@@ -79,6 +79,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