docs: finally some working examples for a lot of commands (#1123)

#### What this PR does / why we need it This adds various indirections on the OCM CLIs own component versions as examples instead of kubelink, which never worked. #### Which issue(s) this PR fixes  fix open-component-model/ocm-project#20
open-component-model · Nov 22, 2024 · 15677a2 · 15677a2
1 parent a065a76
commit 15677a2
Show file tree

Hide file tree

Showing 22 changed files with 52 additions and 42 deletions.
diff --git a/cmds/ocm/commands/ocicmds/artifacts/describe/cmd.go b/cmds/ocm/commands/ocicmds/artifacts/describe/cmd.go
@@ -68,8 +68,8 @@ Per version a detailed, potentially recursive description is printed.
 
 `,
 		Example: `
-$ ocm describe artifact ghcr.io/mandelsoft/kubelink
-$ ocm describe artifact --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm describe artifact ghcr.io/open-component-model/ocm/component-descriptors/ocm.software/ocmcli:0.17.0
+$ ocm describe artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.17.0
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocicmds/artifacts/get/cmd.go b/cmds/ocm/commands/ocicmds/artifacts/get/cmd.go
@@ -44,8 +44,8 @@ Get lists all artifact versions specified, if only a repository is specified
 all tagged artifacts are listed.
 	`,
 		Example: `
-$ ocm get artifact ghcr.io/mandelsoft/kubelink
-$ ocm get artifact --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm get artifact ghcr.io/open-component-model/ocm/component-descriptors/ocm.software/ocmcli
+$ ocm get artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.17.0
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocicmds/artifacts/transfer/cmd.go b/cmds/ocm/commands/ocicmds/artifacts/transfer/cmd.go
@@ -67,10 +67,13 @@ Sources may be specified as
 Note that there is an indirection of "ocm oci artifact" to "ocm transfer artifact" out of convenience.`,
 		Example: `
 # Simple:
-$ ocm oci artifact transfer ghcr.io/open-component-model/kubelink:v1.0.0 gcr.io
-$ ocm oci artifact transfer ghcr.io/open-component-model/kubelink gcr.io
-$ ocm oci artifact transfer ghcr.io/open-component-model/kubelink gcr.io/my-project
-$ ocm oci artifact transfer /tmp/ctf gcr.io/my-project
+$ ocm transfer artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.17.0 ghcr.io/MY_USER/ocmcli:0.17.0
+$ ocm transfer artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image ghcr.io/MY_USER/ocmcli
+$ ocm transfer artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image gcr.io
+$ ocm transfer artifact transfer /tmp/ctf ghcr.io/MY_USER/ocmcli
+
+# Equivalent to ocm transfer artifact:
+$ ocm oci artifact transfer
 
 # Complex:
 # Transfer an artifact from a CTF into an OCI Repository:

diff --git a/cmds/ocm/commands/ocicmds/tags/show/cmd.go b/cmds/ocm/commands/ocicmds/tags/show/cmd.go
@@ -50,7 +50,8 @@ func (o *Command) ForName(name string) *cobra.Command {
 Match tags of an artifact against some patterns.
 `,
 		Example: `
-$ oci show tags ghcr.io/mandelsoft/kubelink
+$ ocm show tags ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image
+$ ocm oci show tags ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocmcmds/components/check/cmd.go b/cmds/ocm/commands/ocmcmds/components/check/cmd.go
@@ -59,8 +59,8 @@ This command checks, whether component versions are completely contained
 in an OCM repository with all its dependent component references.
 `,
 		Example: `
-$ ocm check componentversion ghcr.io/mandelsoft/kubelink
-$ ocm get componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm check componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0
+$ ocm check componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli:0.17.0
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocmcmds/components/get/cmd.go b/cmds/ocm/commands/ocmcmds/components/get/cmd.go
@@ -59,8 +59,8 @@ Get lists all component versions specified, if only a component is specified
 all versions are listed.
 `,
 		Example: `
-$ ocm get componentversion ghcr.io/mandelsoft/kubelink
-$ ocm get componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm get componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0
+$ ocm get componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli:0.17.0
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocmcmds/components/hash/cmd.go b/cmds/ocm/commands/ocmcmds/components/hash/cmd.go
@@ -60,8 +60,8 @@ Hash lists normalized forms for all component versions specified, if only a comp
 all versions are listed.
 `,
 		Example: `
-$ ocm hash componentversion ghcr.io/mandelsoft/kubelink
-$ ocm hash componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm hash componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0
+$ ocm hash componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli:0.17.0
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocmcmds/components/list/cmd.go b/cmds/ocm/commands/ocmcmds/components/list/cmd.go
@@ -53,8 +53,8 @@ List lists the version names of the specified objects, if only a component is sp
 all versions according to the given version constraints are listed.
 `,
 		Example: `
-$ ocm list componentversion ghcr.io/mandelsoft/kubelink
-$ ocm list componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm list componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli
+$ ocm list componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocmcmds/components/sign/cmd.go b/cmds/ocm/commands/ocmcmds/components/sign/cmd.go
@@ -19,7 +19,7 @@ var (
 func NewCommand(ctx clictx.Context, names ...string) *cobra.Command {
 	return signing.NewCommand(ctx, "Sign", true,
 		[]string{"signed", "signing"},
-		desc, "$ ocm sign componentversion --signature mandelsoft --private-key=mandelsoft.key ghcr.io/mandelsoft/kubelink",
+		desc, "$ ocm sign componentversion --signature mysignature --private-key=my.key ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0",
 		utils.Names(Names, names...)...)
 }
 

diff --git a/cmds/ocm/commands/ocmcmds/components/transfer/cmd.go b/cmds/ocm/commands/ocmcmds/components/transfer/cmd.go
@@ -83,8 +83,9 @@ If only a component (instead of a component version) is specified all versions
 are transferred.
 `,
 		Example: `
-$ ocm transfer components -t tgz ghcr.io/mandelsoft/kubelink ctf.tgz
-$ ocm transfer components -t tgz --repo OCIRegistry::ghcr.io mandelsoft/kubelink ctf.tgz
+$ ocm transfer components -t tgz ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0 ./ctf.tgz
+$ ocm transfer components --latest -t tgz --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli ./ctf.tgz
+$ ocm transfer components --latest --copy-resources --type directory ghcr.io/open-component-model/ocm//ocm.software/ocmcli ./ctf
 `,
 		Annotations: map[string]string{"ExampleCodeStyle": "bash"},
 	}

diff --git a/cmds/ocm/commands/ocmcmds/components/verify/cmd.go b/cmds/ocm/commands/ocmcmds/components/verify/cmd.go
@@ -19,7 +19,7 @@ var (
 func NewCommand(ctx clictx.Context, names ...string) *cobra.Command {
 	return signing.NewCommand(ctx, "Verify signature of", false,
 		[]string{"verified", "verifying signature of"},
-		desc, "$ ocm verify componentversion --signature mandelsoft --public-key=mandelsoft.key ghcr.io/mandelsoft/kubelink",
+		desc, "$ ocm verify componentversion --signature mysig --public-key=pub.key ghcr.io/open-component-model/ocm//ocm.software/ocm:0.17.0",
 		utils.Names(Names, names...)...)
 }
 

diff --git a/docs/reference/ocm_check_componentversions.md b/docs/reference/ocm_check_componentversions.md
@@ -89,8 +89,8 @@ The following modes are supported:
 ### Examples
 
 ```bash
-$ ocm check componentversion ghcr.io/mandelsoft/kubelink
-$ ocm get componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm check componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0
+$ ocm check componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli:0.17.0
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_describe_artifacts.md b/docs/reference/ocm_describe_artifacts.md
@@ -73,8 +73,8 @@ The following modes are supported:
 ### Examples
 
 ```bash
-$ ocm describe artifact ghcr.io/mandelsoft/kubelink
-$ ocm describe artifact --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm describe artifact ghcr.io/open-component-model/ocm/component-descriptors/ocm.software/ocmcli:0.17.0
+$ ocm describe artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.17.0
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_get_artifacts.md b/docs/reference/ocm_get_artifacts.md
@@ -78,8 +78,8 @@ The following modes are supported:
 ### Examples
 
 ```bash
-$ ocm get artifact ghcr.io/mandelsoft/kubelink
-$ ocm get artifact --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm get artifact ghcr.io/open-component-model/ocm/component-descriptors/ocm.software/ocmcli
+$ ocm get artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.17.0
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_get_componentversions.md b/docs/reference/ocm_get_componentversions.md
@@ -117,8 +117,8 @@ The following modes are supported:
 ### Examples
 
 ```bash
-$ ocm get componentversion ghcr.io/mandelsoft/kubelink
-$ ocm get componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm get componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0
+$ ocm get componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli:0.17.0
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_hash_componentversions.md b/docs/reference/ocm_hash_componentversions.md
@@ -127,8 +127,8 @@ The following modes are supported:
 ### Examples
 
 ```bash
-$ ocm hash componentversion ghcr.io/mandelsoft/kubelink
-$ ocm hash componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm hash componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0
+$ ocm hash componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli:0.17.0
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_list_componentversions.md b/docs/reference/ocm_list_componentversions.md
@@ -111,8 +111,8 @@ The following modes are supported:
 ### Examples
 
 ```bash
-$ ocm list componentversion ghcr.io/mandelsoft/kubelink
-$ ocm list componentversion --repo OCIRegistry::ghcr.io mandelsoft/kubelink
+$ ocm list componentversion ghcr.io/open-component-model/ocm//ocm.software/ocmcli
+$ ocm list componentversion --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_show_tags.md b/docs/reference/ocm_show_tags.md
@@ -57,7 +57,8 @@ linked library can be used:
 ### Examples
 
 ```bash
-$ oci show tags ghcr.io/mandelsoft/kubelink
+$ ocm show tags ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image
+$ ocm oci show tags ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_sign_componentversions.md b/docs/reference/ocm_sign_componentversions.md
@@ -146,7 +146,7 @@ references.
 ### Examples
 
 ```bash
-$ ocm sign componentversion --signature mandelsoft --private-key=mandelsoft.key ghcr.io/mandelsoft/kubelink
+$ ocm sign componentversion --signature mysignature --private-key=my.key ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_transfer_artifacts.md b/docs/reference/ocm_transfer_artifacts.md
@@ -79,10 +79,13 @@ linked library can be used:
 
 ```bash
 # Simple:
-$ ocm oci artifact transfer ghcr.io/open-component-model/kubelink:v1.0.0 gcr.io
-$ ocm oci artifact transfer ghcr.io/open-component-model/kubelink gcr.io
-$ ocm oci artifact transfer ghcr.io/open-component-model/kubelink gcr.io/my-project
-$ ocm oci artifact transfer /tmp/ctf gcr.io/my-project
+$ ocm transfer artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image:0.17.0 ghcr.io/MY_USER/ocmcli:0.17.0
+$ ocm transfer artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image ghcr.io/MY_USER/ocmcli
+$ ocm transfer artifact ghcr.io/open-component-model/ocm/ocm.software/ocmcli/ocmcli-image gcr.io
+$ ocm transfer artifact transfer /tmp/ctf ghcr.io/MY_USER/ocmcli
+
+# Equivalent to ocm transfer artifact:
+$ ocm oci artifact transfer
 
 # Complex:
 # Transfer an artifact from a CTF into an OCI Repository:

diff --git a/docs/reference/ocm_transfer_componentversions.md b/docs/reference/ocm_transfer_componentversions.md
@@ -241,8 +241,9 @@ this one is used.
 ### Examples
 
 ```bash
-$ ocm transfer components -t tgz ghcr.io/mandelsoft/kubelink ctf.tgz
-$ ocm transfer components -t tgz --repo OCIRegistry::ghcr.io mandelsoft/kubelink ctf.tgz
+$ ocm transfer components -t tgz ghcr.io/open-component-model/ocm//ocm.software/ocmcli:0.17.0 ./ctf.tgz
+$ ocm transfer components --latest -t tgz --repo OCIRegistry::ghcr.io/open-component-model/ocm ocm.software/ocmcli ./ctf.tgz
+$ ocm transfer components --latest --copy-resources --type directory ghcr.io/open-component-model/ocm//ocm.software/ocmcli ./ctf
 ```
 
 ### SEE ALSO

diff --git a/docs/reference/ocm_verify_componentversions.md b/docs/reference/ocm_verify_componentversions.md
@@ -121,7 +121,7 @@ references.
 ### Examples
 
 ```bash
-$ ocm verify componentversion --signature mandelsoft --public-key=mandelsoft.key ghcr.io/mandelsoft/kubelink
+$ ocm verify componentversion --signature mysig --public-key=pub.key ghcr.io/open-component-model/ocm//ocm.software/ocm:0.17.0
 ```
 
 ### SEE ALSO