Improve the help doc for oras manifest index sub commands #1638
Description
Problem
Currently, the help doc for the oras manifest index create command looks like this:
$ oras manifest index create -h
[Experimental] Create and push an index from provided manifests. All manifests should be in the same repository
Example - Create an index from source manifests tagged 'linux-amd64' and 'linux-arm64', and push without tagging:
oras manifest index create localhost:5000/hello linux-amd64 linux-arm64
Example - Create an index from source manifests tagged 'linux-amd64' and 'linux-arm64', and push with the tag 'v1':
oras manifest index create localhost:5000/hello:v1 linux-amd64 linux-arm64
Example - Create an index from source manifests using both tags and digests, and push with tag 'v1':
oras manifest index create localhost:5000/hello:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9
Example - Create an index and push it with multiple tags:
oras manifest index create localhost:5000/hello:tag1,tag2,tag3 linux-amd64 linux-arm64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9
Example - Create and push an index with annotations:
oras manifest index create localhost:5000/hello:v1 linux-amd64 --annotation "key=val"
Example - Create an index and push to an OCI image layout folder 'layout-dir' and tag with 'v1':
oras manifest index create --oci-layout layout-dir:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9
Example - Create an index and save it locally to index.json, auto push will be disabled:
oras manifest index create --output index.json localhost:5000/hello linux-amd64 linux-arm64
Example - Create an index and output the index to stdout, auto push will be disabled:
oras manifest index create localhost:5000/hello linux-arm64 --output - --pretty
Usage:
oras manifest index create [flags] <name>[:<tag[,<tag>][...]] [{<tag>|<digest>}...]
Aliases:
create, packThere are two problems here that could potentially confuse users:
- The usage guide is not clear about which argument is the target to create and which are the source tags
Usage:
oras manifest index create [flags] [:<tag[,][...]] [{|}...]
- Looking at the example for using the
--oci-layoutflag, some users might think that the positional parameters are the argument of the--oci-layoutflag, which is not the case
Example - Create an index and push to an OCI image layout folder 'layout-dir' and tag with 'v1':
oras manifest index create --oci-layout layout-dir:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9
Proposal
To reduce confusion, we can consider:
- Clarifying the purpose of the positional arguments in the usage guide, similar to
oras cp -h. Maybe something like:
Usage:
- oras manifest index create [flags] <name>[:<tag[,<tag>][...]] [{<tag>|<digest>}...]
+ oras manifest index create [flags] <target>[:<tag[,<tag>][...]] <sources>[{<tag>|<digest>}...]- Putting all flags behind the positional arguments in the examples, for example:
Example - Create an index and push to an OCI image layout folder 'layout-dir' and tag with 'v1':
- oras manifest index create --oci-layout layout-dir:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9
+ oras manifest index create layout-dir:v1 linux-amd64 sha256:99e4703fbf30916f549cd6bfa9cdbab614b5392fbe64fdee971359a77073cdf9 --oci-layout