fix: update usage doc for all oras commands (oras-project#596)

Signed-off-by: Billy Zha <[email protected]>

cmd/oras/attach.go

@@ -44,7 +44,7 @@ type attachOptions struct {
 func attachCmd() *cobra.Command {
 	var opts attachOptions
 	cmd := &cobra.Command{
-		Use:   "attach name<:tag|@digest> [file[:type]...]",
+		Use:   "attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<type>] [...]",
 		Short: "[Preview] Attach files to an existing artifact",
 		Long: `[Preview] Attach files to an existing artifact
 
@@ -53,11 +53,15 @@ func attachCmd() *cobra.Command {
 Example - Attach file 'hi.txt' with type 'doc/example' to manifest 'hello:test' in registry 'localhost:5000'
   oras attach --artifact-type doc/example localhost:5000/hello:test hi.txt
 
-Example - Attach and update manifest annotations
+Example - Attach file 'hi.txt' and add annotations from file 'annotation.json'
+  oras attach --artifact-type doc/example --annotation-file annotation.json localhost:5000/hello:latest hi.txt
+
+Example - Attach an artifact with manifest annotations
+  oras attach --artifact-type doc/example --annotation "key1=val1" --annotation "key2=val2" localhost:5000/hello:latest
+
+Example - Attach a file and add manifest annotations
   oras attach --artifact-type doc/example --annotation "key=val" localhost:5000/hello:latest hi.txt
 
-Example - Attach and update annotation from manifest annotation file
-  oras attach --artifact-type doc/example --annotation-file annotation.json localhost:5000/hello:latest hi.txt
 `,
 		Args: cobra.MinimumNArgs(1),
 		PreRunE: func(cmd *cobra.Command, args []string) error {

cmd/oras/blob/delete.go

@@ -38,7 +38,7 @@ type deleteBlobOptions struct {
 func deleteCmd() *cobra.Command {
 	var opts deleteBlobOptions
 	cmd := &cobra.Command{
-		Use:   "delete [flags] <name@digest>",
+		Use:   "delete [flags] <name>@<digest>",
 		Short: "[Preview] Delete a blob from a remote registry",
 		Long: `[Preview] Delete a blob from a remote registry
 

cmd/oras/blob/fetch.go

@@ -42,7 +42,7 @@ type fetchBlobOptions struct {
 func fetchCmd() *cobra.Command {
 	var opts fetchBlobOptions
 	cmd := &cobra.Command{
-		Use:   "fetch [flags] {--output <file>|--descriptor} <name>@<digest>",
+		Use:   "fetch [flags] {--output <file> | --descriptor} <name>@<digest>",
 		Short: "[Preview] Fetch a blob from a remote registry",
 		Long: `[Preview] Fetch a blob from a remote registry
 

cmd/oras/blob/push.go

@@ -42,7 +42,7 @@ type pushBlobOptions struct {
 func pushCmd() *cobra.Command {
 	var opts pushBlobOptions
 	cmd := &cobra.Command{
-		Use:   "push [flags] name[@digest] file",
+		Use:   "push [flags] <name>[@digest] <file>",
 		Short: "[Preview] Push a blob to a remote registry",
 		Long: `[Preview] Push a blob to a remote registry
 

cmd/oras/copy.go

@@ -42,7 +42,7 @@ type copyOptions struct {
 func copyCmd() *cobra.Command {
 	var opts copyOptions
 	cmd := &cobra.Command{
-		Use:     "copy <from-ref> <to-ref>",
+		Use:     "copy [flags] <from>{:<tag>|@<digest>} <to>[:<tag>|@<digest>]",
 		Aliases: []string{"cp"},
 		Short:   "[Preview] Copy artifacts from one target to another",
 		Long: `[Preview] Copy artifacts from one target to another

cmd/oras/discover.go

@@ -45,7 +45,7 @@ type discoverOptions struct {
 func discoverCmd() *cobra.Command {
 	var opts discoverOptions
 	cmd := &cobra.Command{
-		Use:   "discover [options] <name:tag|name@digest>",
+		Use:   "discover [flags] <name>{:<tag>|@<digest>}",
 		Short: "[Preview] Discover referrers of a manifest in the remote registry",
 		Long: `[Preview] Discover referrers of a manifest in the remote registry
 

cmd/oras/login.go

@@ -37,7 +37,7 @@ type loginOptions struct {
 func loginCmd() *cobra.Command {
 	var opts loginOptions
 	cmd := &cobra.Command{
-		Use:   "login registry",
+		Use:   "login [flags] <registry>",
 		Short: "Log in to a remote registry",
 		Long: `Log in to a remote registry
 

cmd/oras/logout.go

@@ -31,7 +31,7 @@ type logoutOptions struct {
 func logoutCmd() *cobra.Command {
 	var opts logoutOptions
 	cmd := &cobra.Command{
-		Use:   "logout registry",
+		Use:   "logout [flags] <registry>",
 		Short: "Log out from a remote registry",
 		Long: `Log out from a remote registry
 

cmd/oras/manifest/delete.go

@@ -39,7 +39,7 @@ type deleteOptions struct {
 func deleteCmd() *cobra.Command {
 	var opts deleteOptions
 	cmd := &cobra.Command{
-		Use:   "delete [flags] name<:tag|@digest>",
+		Use:   "delete [flags] <name>{:<tag>|@<digest>}",
 		Short: "[Preview] Delete a manifest from remote registry",
 		Long: `[Preview] Delete a manifest from remote registry
 

cmd/oras/manifest/fetch.go

@@ -43,7 +43,7 @@ type fetchOptions struct {
 func fetchCmd() *cobra.Command {
 	var opts fetchOptions
 	cmd := &cobra.Command{
-		Use:   "fetch [flags] <name:tag|name@digest>",
+		Use:   "fetch [flags] <name>{:<tag>|@<digest>}",
 		Short: "[Preview] Fetch manifest of the target artifact",
 		Long: `[Preview] Fetch manifest of the target artifact
 

cmd/oras/manifest/fetch_config.go

@@ -46,7 +46,7 @@ type fetchConfigOptions struct {
 func fetchConfigCmd() *cobra.Command {
 	var opts fetchConfigOptions
 	cmd := &cobra.Command{
-		Use:   "fetch-config [flag] name<:tag|@digest>",
+		Use:   "fetch-config [flags] <name>{:<tag>|@<digest>}",
 		Short: "[Preview] Fetch the config of a manifest from a remote registry",
 		Long: `[Preview] Fetch the config of a manifest from a remote registry
 

cmd/oras/manifest/push.go

@@ -43,7 +43,7 @@ type pushOptions struct {
 func pushCmd() *cobra.Command {
 	var opts pushOptions
 	cmd := &cobra.Command{
-		Use:   "push [flags] name[:tag|@digest] file",
+		Use:   "push [flags] <name>[:<tag>|@<digest>] <file>",
 		Short: "[Preview] Push a manifest to remote registry",
 		Long: `[Preview] Push a manifest to remote registry
 

cmd/oras/pull.go

@@ -47,7 +47,7 @@ type pullOptions struct {
 func pullCmd() *cobra.Command {
 	var opts pullOptions
 	cmd := &cobra.Command{
-		Use:   "pull <name:tag|name@digest>",
+		Use:   "pull [flags] <name>{:<tag>|@<digest>}",
 		Short: "Pull files from remote registry",
 		Long: `Pull files from remote registry
 

cmd/oras/push.go

@@ -46,7 +46,7 @@ type pushOptions struct {
 func pushCmd() *cobra.Command {
 	var opts pushOptions
 	cmd := &cobra.Command{
-		Use:   "push name[:tag|@digest] file[:type] [file...]",
+		Use:   "push [flags] <name>[:<tag>|@<digest>] <file>[:<type>] [...]",
 		Short: "Push files to remote registry",
 		Long: `Push files to remote registry
 

cmd/oras/repository/list.go

@@ -32,7 +32,7 @@ type repositoryOptions struct {
 func listCmd() *cobra.Command {
 	var opts repositoryOptions
 	cmd := &cobra.Command{
-		Use:   "list [flags] REGISTRY",
+		Use:   "list [flags] <registry>",
 		Short: "[Preview] List the repositories under the registry",
 		Long: `[Preview] List the repositories under the registry
 

cmd/oras/repository/show-tags.go

@@ -32,7 +32,7 @@ type showTagsOptions struct {
 func showTagsCmd() *cobra.Command {
 	var opts showTagsOptions
 	cmd := &cobra.Command{
-		Use:   "show-tags [flags] REPOSITORY",
+		Use:   "show-tags [flags] <name>",
 		Short: "[Preview] Show tags of the target repository",
 		Long: `[Preview] Show tags of the target repository
 

cmd/oras/tag/tag.go

@@ -40,7 +40,7 @@ type tagOptions struct {
 func TagCmd() *cobra.Command {
 	var opts tagOptions
 	cmd := &cobra.Command{
-		Use:   "tag [flags] name<:tag|@digest> <new_tag...>",
+		Use:   "tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]",
 		Short: "[Preview] tag a manifest in the remote registry",
 		Long: `[Preview] tag a manifest in the remote registry