From d1fe4d0f7f99d0cbcf5d303c2144de99a3fb3894 Mon Sep 17 00:00:00 2001 From: Xiaoxuan Wang <103478229+wangxiaoxuan273@users.noreply.github.com> Date: Tue, 10 Sep 2024 16:07:59 +0800 Subject: [PATCH] docs: add examples for --format (#1497) Signed-off-by: Xiaoxuan Wang --- cmd/oras/root/attach.go | 6 ++++++ cmd/oras/root/discover.go | 16 +++++++++------- cmd/oras/root/manifest/fetch.go | 3 +++ cmd/oras/root/pull.go | 6 ++++++ cmd/oras/root/push.go | 6 ++++++ 5 files changed, 30 insertions(+), 7 deletions(-) diff --git a/cmd/oras/root/attach.go b/cmd/oras/root/attach.go index 89a570210..37d2ddf98 100644 --- a/cmd/oras/root/attach.go +++ b/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 diff --git a/cmd/oras/root/discover.go b/cmd/oras/root/discover.go index 8e3f4638d..34d3bccb0 100644 --- a/cmd/oras/root/discover.go +++ b/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 { diff --git a/cmd/oras/root/manifest/fetch.go b/cmd/oras/root/manifest/fetch.go index 8476d12d7..74381cada 100644 --- a/cmd/oras/root/manifest/fetch.go +++ b/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 diff --git a/cmd/oras/root/pull.go b/cmd/oras/root/pull.go index 4b01ec779..6ab3a3dff 100644 --- a/cmd/oras/root/pull.go +++ b/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 diff --git a/cmd/oras/root/push.go b/cmd/oras/root/push.go index 1eb11e523..f8afa6a3c 100644 --- a/cmd/oras/root/push.go +++ b/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