feat: support `--format` for `oras repo ls` #1758

Wwwsylvia · 2025-06-26T11:28:23Z

What this PR does / why we need it:
Introduces a new --format flag to the oras repo ls command, with 3 format options: text, json, and go-template.

--format text: Equivalent to the default output, which remains unchanged
--format json: Outputs a JSON object with registry and repositories fields, where repositories include the full repository names
--format go-template: Uses the same underlying model as the JSON structure

Spec: #1763

Introduced behaviors:

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes part of #1547

Please check the following list:

Does the affected code have corresponding tests, e.g. unit test, E2E test?
Does this change require a documentation update?
Does this introduce breaking changes that would require an announcement or bumping the major version?
Do all new files have an appropriate license header?

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

codecov · 2025-06-26T11:34:56Z

Codecov Report

Attention: Patch coverage is 92.00000% with 6 lines in your changes missing coverage. Please review.

Project coverage is 85.39%. Comparing base (fd82860) to head (92fa56d).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/oras/root/repo/ls.go	64.70%	4 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1758      +/-   ##
==========================================
+ Coverage   85.29%   85.39%   +0.10%     
==========================================
  Files         133      137       +4     
  Lines        5882     5951      +69     
==========================================
+ Hits         5017     5082      +65     
- Misses        616      618       +2     
- Partials      249      251       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

shizhMSFT

LGTM

TerryHowe

/lgtm

cmd/oras/internal/display/metadata/json/repo_list.go

qweeah

Do we want to update the spec first? This implementation is not aligned to #733. E.g. if a sub namespace is used for MCR, the output is not repository but the output is saying it is

# E.g. `oras` is not a repository but `oss/v2/oras-project/oras` is
> oras repo ls mcr.microsoft.com/oss/v2/oras-project --format json
{
  "repositories": [
    "oras"
  ]
}

shizhMSFT · 2025-06-27T09:26:50Z

Do we want to update the spec first? This implementation is not aligned to #733. E.g. if a sub namespace is used for MCR, the output is not repository but the output is saying it is
# E.g. `oras` is not a repository but `oss/v2/oras-project/oras` is
> oras repo ls mcr.microsoft.com/oss/v2/oras-project --format json
{
  "repositories": [
    "oras"
  ]
}

Nice catch, @qweeah !

I think we should have a refined model like

$ oras repo ls mcr.microsoft.com/oss/v2/oras-project --format json
{
  "registry": "mcr.microsoft.com",
  "repositories": [
    "oss/v2/oras-project/oras"
  ]
}

so that it is consistent with the output of the distribution catalog API.

Wwwsylvia · 2025-06-27T09:32:42Z

Do we want to update the spec first? This implementation is not aligned to #733. E.g. if a sub namespace is used for MCR, the output is not repository but the output is saying it is
# E.g. `oras` is not a repository but `oss/v2/oras-project/oras` is
> oras repo ls mcr.microsoft.com/oss/v2/oras-project --format json
{
  "repositories": [
    "oras"
  ]
}
Nice catch, @qweeah !

I think we should have a refined model like
$ oras repo ls mcr.microsoft.com/oss/v2/oras-project --format json
{
  "registry": "mcr.microsoft.com",
  "repositories": [
    "oss/v2/oras-project/oras"
  ]
}
so that it is consistent with the output of the distribution catalog API.

SGTM

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

cmd/oras/internal/display/metadata/interface.go

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

Copilot

Pull Request Overview

Adds support for a new --format flag to oras repo ls, enabling text, json, and go-template outputs.

Integrates option.Format into the repo ls command and delegates output to new display handlers.
Updates command help/examples to document the flag and extends E2E tests for help, JSON, and Go-template formats.
Introduces display packages (text, JSON, template, model, interface) and unit tests for handler initialization.

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/e2e/suite/command/repo.go	Added E2E tests for `--format` help, JSON, and go-template outputs
cmd/oras/root/repo/tags.go	Updated help examples to mention JSON and Go template formats
cmd/oras/root/repo/ls.go	Integrated `--format` flag, display handlers, and updated examples
cmd/oras/internal/display/metadata/text/repo_list.go	Added text format handler for `repo ls`
cmd/oras/internal/display/metadata/template/repo_list.go	Added template format handler for `repo ls`
cmd/oras/internal/display/metadata/model/repo_list.go	Added metadata model for repositories
cmd/oras/internal/display/metadata/json/repo_list.go	Added JSON format handler for `repo ls`
cmd/oras/internal/display/metadata/interface.go	Defined the `RepoListHandler` interface
cmd/oras/internal/display/handler.go	Implemented the `NewRepoListHandler` factory
cmd/oras/internal/display/handler_test.go	Added unit tests for `NewRepoListHandler`

Comments suppressed due to low confidence (2)

cmd/oras/internal/display/handler_test.go:123

[nitpick] Current tests only verify handler creation. Consider adding tests that call OnRepositoryListed and Render for each format (text, JSON, template) to ensure actual output matches expectations.

			handler, err := NewRepoListHandler(os.Stdout, tt.format, registry, namespace)

test/e2e/suite/command/repo.go:156

The test calls json.Unmarshal but the encoding/json package is not imported, causing a compile error. Please add import "encoding/json" to this file.

			Expect(json.Unmarshal(bytes, &result)).ShouldNot(HaveOccurred())

shizhMSFT

LGTM

cmd/oras/internal/display/handler.go

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

shizhMSFT

LGTM

qweeah

LGTM

Wwwsylvia added 7 commits June 26, 2025 13:00

first draft

256c49b

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

add unit tests

4435df7

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

tags unit tests

b4f73fc

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

refactor

2c75666

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

refactor more

f6b03dc

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

e2e

cf918b4

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

fix line endings

7ef482e

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

rephrase

edf180c

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

Wwwsylvia marked this pull request as ready for review June 26, 2025 11:56

Wwwsylvia requested review from sajayantony, shizhMSFT, SteveLasker, qweeah and TerryHowe as code owners June 26, 2025 11:56

shizhMSFT approved these changes Jun 26, 2025

View reviewed changes

TerryHowe reviewed Jun 26, 2025

View reviewed changes

cmd/oras/internal/display/metadata/json/repo_list.go Show resolved Hide resolved

qweeah requested changes Jun 27, 2025

View reviewed changes

Wwwsylvia added 2 commits July 2, 2025 10:42

refactor

04f3ecf

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

refine

1e56dea

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

Wwwsylvia marked this pull request as draft July 2, 2025 02:56

Wwwsylvia added 5 commits July 2, 2025 11:17

update e2e

84be683

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

add e2e

0ccc5de

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

add test for go template

d8cf2e5

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

fix format

05b7482

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

rename

9c4f0ba

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

Wwwsylvia marked this pull request as ready for review July 2, 2025 07:21

Wwwsylvia requested a review from Copilot July 2, 2025 07:58

This comment was marked as outdated.

Sign in to view

Wwwsylvia mentioned this pull request Jul 2, 2025

docs(spec): define output formats for oras repo commands #1763

Merged

4 tasks

shizhMSFT reviewed Jul 2, 2025

View reviewed changes

cmd/oras/internal/display/metadata/interface.go Outdated Show resolved Hide resolved

Wwwsylvia added 3 commits July 2, 2025 18:14

fix

9048ccd

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

refactor fix

f846ae4

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

fix fix

62ae79c

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

Wwwsylvia requested a review from Copilot July 2, 2025 10:29

Copilot AI reviewed Jul 2, 2025

View reviewed changes

shizhMSFT approved these changes Jul 2, 2025

View reviewed changes

cmd/oras/internal/display/handler.go Outdated Show resolved Hide resolved

Wwwsylvia added 2 commits July 2, 2025 18:49

optimize

44f05f7

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

nit

d7b961b

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

shizhMSFT approved these changes Jul 2, 2025

View reviewed changes

shizhMSFT requested a review from qweeah July 2, 2025 10:53

qweeah approved these changes Jul 3, 2025

View reviewed changes

Merge branch 'main' into repo_ls_format

92fa56d

Wwwsylvia merged commit 4264b96 into oras-project:main Jul 4, 2025
8 checks passed

Wwwsylvia deleted the repo_ls_format branch July 4, 2025 04:31

This was referenced Aug 7, 2025

bump: tag and release ORAS CLI v1.3.0-beta.4 #1798

Closed

bump: tag and release ORAS CLI v1.3.0-beta.4 #1799

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: support `--format` for `oras repo ls` #1758

feat: support `--format` for `oras repo ls` #1758

Uh oh!

Wwwsylvia commented Jun 26, 2025 •

edited

Loading

Uh oh!

codecov bot commented Jun 26, 2025 •

edited

Loading

Uh oh!

shizhMSFT left a comment

Uh oh!

TerryHowe left a comment

Uh oh!

Uh oh!

qweeah left a comment

Uh oh!

shizhMSFT commented Jun 27, 2025 •

edited

Loading

Uh oh!

Wwwsylvia commented Jun 27, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

shizhMSFT left a comment

Uh oh!

Uh oh!

shizhMSFT left a comment

Uh oh!

qweeah left a comment

Uh oh!

Uh oh!

Uh oh!

feat: support --format for oras repo ls #1758

feat: support --format for oras repo ls #1758

Uh oh!

Conversation

Wwwsylvia commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

shizhMSFT left a comment

Choose a reason for hiding this comment

Uh oh!

TerryHowe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

qweeah left a comment

Choose a reason for hiding this comment

Uh oh!

shizhMSFT commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Wwwsylvia commented Jun 27, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

shizhMSFT left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shizhMSFT left a comment

Choose a reason for hiding this comment

Uh oh!

qweeah left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

feat: support `--format` for `oras repo ls` #1758

feat: support `--format` for `oras repo ls` #1758

Wwwsylvia commented Jun 26, 2025 •

edited

Loading

codecov bot commented Jun 26, 2025 •

edited

Loading

shizhMSFT commented Jun 27, 2025 •

edited

Loading