oras-project / oras

OCI registry client - managing content like artifacts, images, packages
https://oras.land
Apache License 2.0
1.52k stars 181 forks source link

improve error message of `oras attach` when subject artifact is not specified #1424

Closed qweeah closed 5 months ago

qweeah commented 5 months ago

When using oras attach, if a user forgot to provide the subject artifact reference and only specifies one to-be-uploaded file, ORAS CLI will output (tested in bash, different shell might have different output):

> ARTIFACT=
> oras attach --artifact-type test/example $ARTIFACT./test.json
Error: neither file nor annotation provided in the command
Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<layer_media_type>] [...]
To attach to an existing artifact, please provide files via argument or annotations via flag "--annotation". Run "oras attach -h" for more options and examplesdigest]

Input was parsed under a wrong consumption: user does specify subject artifact reference ./layers, which actually is a file reference to be attached. This error can be avoided by parsing the only input argument. If the reference is valid, continue with current output. If it's not, give corresponding hint like:

Error: "./test.json" is an invalid artifact reference
Did you forget to specify a subject artifact?
qweeah commented 5 months ago

This should also resolve part of #1404

FeynmanZhou commented 5 months ago

Can you pls also add the wrong oras attach command in this issue?

qweeah commented 5 months ago

Sample error output (phrasing and wording still TBD)

> ./bin/linux/amd64/oras attach --artifact-type test/example "a-------" 
Error: "a-------": invalid reference: missing registry or repository
Have you specified an artifact reference to attach to? Please make sure the provided reference is in the form of <registry>/<repo>[:tag|@digest][:tag|@digest]

Depends on different behavior of shell, if an empty env variable is interpolated into "" (zsh)

> ARTIFACT=
> ./bin/linux/amd64/oras attach --artifact-type test/example $ARTIFACT my.json
Error: "my.json": invalid reference: missing registry or repository
Have you specified an artifact reference to attach to? Please make sure the provided reference is in the form of <registry>/<repo>[:tag|@digest]
> ./bin/linux/amd64/oras attach localhost:5000/test my.json --artifact-type test/example
Error: "localhost:5000/test": no tag or digest specified
Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<layer_media_type>] [...]
Please specify a reference in the form of "<name>:<tag>" or "<name>@<digest>". Run "oras attach -h" for more options and examples

If an empty env variable is omitted (bash)

> ARTIFACT=
> ./bin/linux/amd64/oras attach --artifact-type test/example $ARTIFACT ./my.json
Error: "./my.json": no tag or digest specified
Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<layer_media_type>] [...]
Have you specified an artifact reference to attach to? Please specify a reference in the form of "<name>:<tag>" or "<name>@<digest>". Run "oras attach -h" for more options and examples
FeynmanZhou commented 5 months ago

@qweeah For this case, how about improving the error message as follows:

> oras attach --artifact-type test/example $ARTIFACT ./layers 
Error: "./layers" is an invalid artifact reference.
Usage: oras attach [flags] --artifact-type=<type> <name>{:<tag>|@<digest>} <file>[:<layer_media_type>] | --annotation "key=val"
To attach files to an object, please specify a valid artifact reference and files via arguments in sequence". Run "oras attach -h" for more options and examples.