Bad UX of `--oci-layout-path` flag working with `oras repo tags`

[Wwwsylvia]

What happened in your environment?

I have an OCI layout that contains several tags, some are in format of FQDN. I can list the tags by running oras repo tags --oci-layout $dirName, for example:

$ oras repo tags --oci-layout ./repo
example.registry.com/foo:latest
test.com/bar:v1
v2

However, if I replace --oci-layout with --oci-layout-path like this, there will be an error:

$ oras repo tags --oci-layout-path ./repo
Error: "oras repo tags" requires exactly 1 argument but got 0
Usage: oras repo tags [flags] <name>
Please specify exactly 1 argument as the target repository to list tags from. Run "oras repo tags -h" for more options and examples

The right way is to add one more parameter as the repository name, which should be an empty string in this case:

oras repo tags --oci-layout-path ./repo ""
example.registry.com/foo:latest
test.com/bar:v1
v2

This UX is strange and not intuitive.

What did you expect to happen?

The --oci-layout=path flag may not be applicable to the oras repo tags command.

How can we reproduce it?

1. Run oras repo tags --oci-layout $dirName
2. Run oras repo tags --oci-layout-path $dirName ""

What is the version of your ORAS CLI?

Version: 1.3.0-beta.1 Go version: go1.23.4 OS/Arch: linux/amd64 Git commit: 2ca02f6f6514200366df26ba9ef6d1b311629dad Git tree state: clean

What is your OS environment?

Ubuntu 24.04 in WSL

Are you willing to submit PRs to fix it?

• [ ] Yes, I am willing to fix it.

[bupd]

I hope I can help you with this. Should I open a PR?

cc // @Wwwsylvia, @FeynmanZhou

[Wwwsylvia]

Hi @bupd , thank you showing interest! Before jumping directly to the implementation, you may propose a design here in the issue comment, and the community can discuss it together.

[github-actions[bot]]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[wangxiaoxuan273]

Origin of the oci-layout-path flag: https://github.com/oras-project/oras/issues/1505 , https://github.com/oras-project/oras/pull/1507

It is created to address the case of a tag having colons.

[wangxiaoxuan273]

As oci-layout-path flag is now in option.Target, 16 commands has it. The flag is created to address the case of a tag containing colons. As all these 16 commands accept tag input, the flag is indeed needed for all of them.

Here is a possible use case in which oci-layout-path is needed for oras repo tags. It is similar to #1505 and #1686.

As shown in the repo tags help doc, repo tags has the following usage which accepts a tag:

Example - [Experimental] Show tags associated with a particular tagged resource:
  oras repo tags localhost:5000/hello:latest

Example - [Experimental] Show tags associated with a digest:
  oras repo tags localhost:5000/hello@sha256:c551125a624189cece9135981621f3f3144564ddabe14b523507bf74c2281d9b

Consider an oci layout with the following tags:

oras repo tags --oci-layout ~/my-oci
1.22
1.23
1.24
1.25
my.tag.with:colon

If I want to check the tags associated with my.tag.with:colon, the correct way is to use the following command: oras repo tags --oci-layout-path ~/my-oci my.tag.with:colon

Without the oci-layout-path flag, the following command will give an error:

oras repo tags --oci-layout ~/my-oci:my.tag.with:colon
Error: invalid argument "/root/temp-oci:my.tag.with:colon": failed to find path "/root/temp-oci:my.tag.with": stat /root/temp-oci:my.tag.with: no such file or directory

This is the same error the users got in #1505 and #1686, and the reason the --oci-layout-path is introduced.

Given the above, the error message posted in this issue is correct:

$ oras repo tags --oci-layout-path ./repo
Error: "oras repo tags" requires exactly 1 argument but got 0

[wangxiaoxuan273]

Given that --oci-layout-path is necessary and should not be removed from option.Target, now the issue is: we need to improve the UX when the destination target reference argument is empty.

For example, when pushing a file without a tag to an oci layout: oras push --oci-layout-path ./my-oci/ "" file.md

When using oras repo tags without a tag, as mentioned in this issue: oras repo tags --oci-layout-path ./my-oci/ ""

[shizhMSFT]

Given

$ oras repo tags --oci-layout ./repo
example.registry.com/foo:latest
test.com/bar:v1
v2

My expected behavior would be

$ oras repo tags --oci-layout-path ./repo example.registry.com/foo
latest
$ oras repo tags --oci-layout-path ./repo test.com/bar
v1

It is still oras repo tags --oci-layout-path <path> <name> where <name> is the full repository name.

[FeynmanZhou]

Given that --oci-layout-path is necessary and should not be removed from option.Target, now the issue is: we need to improve the UX when the destination target reference argument is empty.

For example, when pushing a file without a tag to an oci layout: oras push --oci-layout-path ./my-oci/ "" file.md

When using oras repo tags without a tag, as mentioned in this issue: oras repo tags --oci-layout-path ./my-oci/ ""

@wangxiaoxuan273 Thanks for the summary. In your example, when pushing a file without a tag to an oci layout, should we use --oci-layout instead? Is "" an empty positional parameter that is supposed to be a reference?

[FeynmanZhou]

@shizhMSFT 's proposal looks intuitive enough to me.

[wangxiaoxuan273]

In your example, when pushing a file without a tag to an oci layout, should we use --oci-layout instead?

Yes, we should recommend users to use --oci-layout.

Is "" an empty positional parameter that is supposed to be a reference?

Correct.

[FeynmanZhou]

Given

$ oras repo tags --oci-layout ./repo example.registry.com/foo:latest test.com/bar:v1 v2 My expected behavior would be

$ oras repo tags --oci-layout-path ./repo example.registry.com/foo latest $ oras repo tags --oci-layout-path ./repo test.com/bar v1 It is still oras repo tags --oci-layout-path <path> <name> where <name> is the full repository name.

@mauriciovasquezbernal could you also take a look at this proposed behavior?

[mauriciovasquezbernal]

@mauriciovasquezbernal could you also take a look at this proposed behavior?

I don't have the time right now, but I could give it a try in about two weeks

[FeynmanZhou]

@mauriciovasquezbernal Thanks for the response. We will implement it as @shizhMSFT proposed above. As this flag is still experimental, it's subject to be changed once we received feedback from the community.