Implement sort logic for winget list output by Madhusudhan-MSFT · Pull Request #6191 · microsoft/winget-cli

Madhusudhan-MSFT · 2026-04-29T21:11:36Z

Summary

Implements the sort logic for winget list output, completing the feature requested in #4238. Builds on PR #6177 (settings parsing + CLI handling).

Changes

Sort orchestration (WorkflowBase.cpp):

SortInstalledPackagesTableLines — resolves sort fields from CLI --sort > settings output.sortOrder > query-aware default, determines direction, sorts via std::stable_sort, applies permutation back.
When the free-text query (-q) is used and no sort preference is configured, relevance ordering is preserved. If output.sortOrder is configured, it is respected even with queries.
FAIL_FAST_MSG for unrecognized sort field values — ensures invalid enum values crash loudly in debug builds.

Sort helper (PackageTableSortHelper.h/.cpp):

SortablePackageEntry — holds pre-computed case-folded sortable fields, computed only for fields needed via ComputeSortFieldMask bitmask optimization.
CompareByField — case-insensitive ordinal comparison using pre-computed FoldCase values.
SortBy — template sort executor used by the workflow; standalone SortEntries wrapper available for unit tests.
SortField enum uses flag-bit values (uint32_t) with DEFINE_ENUM_FLAG_OPERATORS for efficient bitmask field tracking.

CLI integration (ListCommand.cpp):

--sort (repeatable, limit 6), --ascending/--asc, --descending/--desc arguments.

Argument validation (Command.cpp):

Validates --sort values in ValidateArguments, following the --scope/--authentication-mode pattern.

Documentation (list.md):

--sort, --ascending, --descending in options table. New "Sorting output" section.

⚠️ Behavior change: default sort order

Previously, winget list output preserved the source's natural ordering (source-determined relevance ranking). This PR changes the default to sort alphabetically by name (ascending) when no --sort argument, no -q query, and no output.sortOrder setting is configured.

Scenario	Behavior
No query, no settings, no `--sort`	Sorts by name (ascending) — new default
`-q` query with no sort preference	Preserves source relevance ordering (unchanged)
`--sort relevance` or `"sortOrder": ["relevance"]`	Preserves source ordering explicitly
`"sortOrder": []` (empty array)	Same as no setting — applies default name sort
`output.sortOrder` configured + `-q` query	Settings override relevance (explicit user preference wins)

To restore previous (source-determined) ordering:

CLI: winget list --sort relevance
Settings: { "output": { "sortOrder": ["relevance"] } }

Note: An empty sortOrder array is equivalent to the setting not being present — it does not disable sorting. Use "relevance" explicitly to preserve source ordering.

Design decisions

Decision	Rationale
Default sort by name	When no settings and no query, sort alphabetically by name — most natural default for browsing installed packages.
Relevance preservation with queries	Free-text query (`-q`) without configured sort preserves source relevance ranking. Settings override this if configured — explicit user preference takes priority.
`stable_sort`	Preserves relative order for multi-field sorting (e.g., `--sort source --sort name` groups by source, alphabetical within).
Flag-bit `SortField` enum	Enables `ComputeSortFieldMask` to skip unused field extraction — measurable win for large package lists.
Pre-computed `FoldCase`	Expensive case-folding done once per entry at construction, not on every comparison call.
`FAIL_FAST_MSG` on invalid sort	Catches enum drift at development time rather than silent misbehavior.

How validated

Unit tests — 20 test cases:

18 sort tests in PackageTableSortHelper.cpp: single/multi-field sorting, both directions, edge cases, case-insensitive comparison, relevance no-op
1 drift detection test in Command.cpp: reads ListCommand::GetArguments() limit and validates against known ConvertToSortField strings — breaks if enum changes without updating limit
1 enforcement test in Command.cpp: verifies SetCountLimit(6) rejects 7 --sort values with TooManyArgError

Manual testing — 21 scenarios on wingetdev (Debug x64): defaults, single/multi-field sorts, direction flags, query + sort interaction, settings precedence, edge cases, invalid input. All passing.

Fixes #4238

Trenly · 2026-04-29T21:14:53Z

Is this only applicable to winget list or to any command that presents the user with a table of packages (upgrade, search, pin, etc.)

Trenly · 2026-04-29T21:17:21Z

Key behavior to note: Settings sortOrder is intentionally NOT applied when query/filter arguments are present. Only explicit --sort CLI arguments can override relevance ordering. The --descending flag applies to whichever sort fields are active (CLI or settings).

This seems like it would be counter to what a user would want. If I did winget list Microsoft and my default sort order in settings is Name I'd expect both the filter and the sorting to work

Madhusudhan-MSFT · 2026-04-29T21:45:15Z

Is this only applicable to winget list or to any command that presents the user with a table of packages (upgrade, search, pin, etc.)

The current implementation is scoped to winget list per the feature request in #4238. The sort infrastructure (schema, settings, argument definitions) was designed to be reusable, so extending to other table-outputting commands like upgrade or search would be straightforward if there's demand for it.

Madhusudhan-MSFT · 2026-04-29T21:45:27Z

This seems like it would be counter to what a user would want. If I did winget list Microsoft and my default sort order in settings is Name I'd expect both the filter and the sorting to work

This was discussed and agreed upon during the initial design. The intent is to preserve source relevance ordering for queries since a settings-based sort could push the best match down without the user realizing why. Explicit --sort always works with queries (e.g., winget list Microsoft --sort name).

@denelon — I believe this aligns with what we discussed during the design phase, would you mind confirming?

Trenly · 2026-04-29T22:05:25Z

if there's demand for it.

I think there is, but agree with the approach of limiting the scope for now and letting Demitrius figure out when to bring the rest in

JohnMcPMS · 2026-04-29T22:38:13Z

This seems like it would be counter to what a user would want. If I did winget list Microsoft and my default sort order in settings is Name I'd expect both the filter and the sorting to work

This was discussed and agreed upon during the initial design. The intent is to preserve source relevance ordering for queries since a settings-based sort could push the best match down without the user realizing why. Explicit --sort always works with queries (e.g., winget list Microsoft --sort name).

@denelon — I believe this aligns with what we discussed during the design phase, would you mind confirming?

From the design portion, my feedback was that the default behavior should be to remain unchanged with a query but could have a new ordering without a query. If the user does supply a setting value, my expectation would be that it would be used with or without a query unless overridden with a command line argument.

What constitutes a query? Probably only the actual query argument, not id or other fields. Relevance would largely by the same for those already.

Madhusudhan-MSFT · 2026-04-29T23:26:15Z

From the design portion, my feedback was that the default behavior should be to remain unchanged with a query but could have a new ordering without a query. If the user does supply a setting value, my expectation would be that it would be used with or without a query unless overridden with a command line argument.

What constitutes a query? Probably only the actual query argument, not id or other fields. Relevance would largely by the same for those already.

Thanks for the clarification, John. Updated in 70bd157e:

Default unchanged — without output.sortOrder configured, positional query preserves relevance as before
Settings always honored — if user configures output.sortOrder, it applies regardless of arguments (user explicitly opted in)
"Query" narrowed — only the positional query argument (not --id/--name/--tag) is considered relevance-affecting in the no-settings case

Removed HasRelevanceAffectingArgs in favor of sortFields.empty() && Args.Contains(Query).

… add comprehensive tests

…pp file ## Summary Every other Workflow header in the project follows the declarations-only convention with a matching .cpp file. ListSortHelper.h was the only outlier using inline implementations. This refactor aligns it with the codebase convention and eliminates the duplicated sort loop between ListSortHelper.h and WorkflowBase.cpp. ## Changes - **ListSortHelper.h → declarations only**: Remove inline implementations of CompareByField and SortEntries, keeping only the struct definition and function signatures - **ListSortHelper.cpp**: New compilation unit with the extracted implementations of CompareByField and SortEntries - **WorkflowBase.cpp sort integration**: Replace the duplicated inline sort loop with an index-based permutation sort that projects InstalledPackagesTableLine into SortablePackageEntry and delegates field comparison to the shared CompareByField - Remove the local CompareByField adapter that was creating temporary SortablePackageEntry copies per comparison call - Align include path and grouping with repo conventions (bare sibling name, local before system) - Simplify GetArgs access to match established MultiQueryFlow pattern ## Impact - Sort logic now lives in a single shared location, reusable by future commands (search, upgrade, font list) without duplication - Follows the established Workflows/ header convention (24/24 other headers use .h + .cpp) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add --sort, --ascending, and --descending options to the options table. Add new 'Sorting output' section documenting: - CLI sort arguments with multi-field examples - Settings-based sortOrder configuration - Resolution order (CLI > settings > default) - Relevance protection behavior for queries

Validate --sort argument values in Command::ValidateArguments following the same pattern as --scope and --authentication-mode validation. Invalid values produce a clear error message listing valid options (name, id, version, source, available, relevance). Centralized in Command.cpp so any future command adding --sort gets validation automatically.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…edback - Remove HasRelevanceAffectingArgs function (overly broad filter) - Narrow relevance preservation to only the free-text query argument - Settings output.sortOrder now applies even when query is present (user explicitly configured sort preference takes priority) - Filter args (--id, --name, --tag etc.) no longer block settings sort since they use exact/substring matching with no meaningful relevance - Update list.md documentation to reflect new behavior - Resolution: CLI --sort > settings (always) > default relevance (query only)

- Fix comment: 'enable' -> 'ease' unit testing (not impossible, just decoupled) - Remove stale comment from deleted HasRelevanceAffectingArgs function - Add THROW_HR(E_UNEXPECTED) assertion for invalid sort values that bypass validation - Change --sort count limit from 7 to 6 (matches actual SortField enum count)

When no sort preferences are configured (no CLI --sort, no settings) and no positional query is present, default to sorting by name ascending for deterministic, user-friendly output. With a positional query, relevance ordering is preserved unless the user explicitly configures sort preferences. Update list.md to document this conditional default behavior.

Restructure ListSortHelper to own the production sort path: - SortablePackageEntry now precomputes case-folded strings and parsed versions at construction time, avoiding repeated FoldCase/Version parsing during comparisons. - Add OriginalIndex field so entries track their source position. - Add SortBy<T> template that converts arbitrary item vectors into SortablePackageEntry projections, sorts, then reorders the source vector to match. This is the production code path. - WorkflowBase calls SortBy with a conversion lambda, replacing the inline permutation sort. - SortEntries is no longer test-only — it is the same code path that production uses via SortBy. - Add SortBy template tests to validate the end-to-end pipeline with custom source types.

Rename to reflect broader scope — the helper sorts package table rows for any table-based command (list, search, upgrade), not just list.

Change SortField to flag-bit enum (uint32_t) and add DEFINE_ENUM_FLAG_OPERATORS so sort fields compose into a bitmask. SortBy computes the mask once and passes it through the converter to SortablePackageEntry's constructor, which now only precomputes fields that are actually needed for the requested sort.

- Add static_assert on SortField::Available at enum definition site to catch new values that bypass constructor handling. - Replace invalid-sort assertion with FAIL_FAST_MSG for clearer diagnostics. - Collapse two consecutive sortFields.empty() checks into a single branch. - Format SortablePackageEntry constructor arguments one-per-line. - Add --query example to list.md Example queries section.

- `WI_IsAnyFlagSet` was used for single-flag checks where `WI_IsFlagSet` is the correct API - `ComputeSortFieldMask` was defined inline in the header instead of the .cpp file - `SortInstalledPackagesTableLines` was called at three separate call sites instead of being encapsulated inside `OutputInstalledPackages` - Default-sort bypass only checked `Query` argument, missing the `MultiQuery` path - Test assertions validated only a single field (name or ID), providing no cross-field verification of sort correctness - Replace all five `WI_IsAnyFlagSet` calls with `WI_IsFlagSet` for single-flag conditionals - Move `ComputeSortFieldMask` body to PackageTableSortHelper.cpp, leaving only the declaration in the header - Consolidate sort invocation inside `OutputInstalledPackages`, reducing three call sites to one - Add `MultiQuery` argument check alongside `Query` for relevance-preserving default - Replace `GetNames`/`GetIds` test helpers with `ValidateSortResult` that asserts all six precomputed fields (FoldedName, FoldedId, FoldedSource, HasAvailableVersion, ParsedInstalledVersion, ParsedAvailableVersion) per entry - Add release notes entry for sortable list output - No behavioral change to end users — fixes are code quality improvements and correctness for the `--query` multi-value path - Test suite now validates complete sort state rather than a single projection, catching regressions in any field computation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

JohnMcPMS · 2026-05-07T00:37:29Z

nit: Eventually all of this "determine the sort fields and order" will end up in the helper file as well.

I meant all of it. I don't see a reason to pessimistically split out the context/argument extraction from the resolution portion. If we expand to other commands, the arguments are likely to stay the same. Maybe certain fields are not valid and can be checked by those commands, but this shared portion should be able to stay unchanged.

## Problem - Sort argument count limit was hardcoded to a magic number (6), creating drift risk when new SortField values are added - SortField::Relevance occupied 0x0, conflicting with bitmask zero-initialization semantics - Sort resolution logic was inlined in WorkflowBase.cpp, making it untestable in isolation - Available version comparison used a separate bool flag instead of leveraging std::optional semantics - Missing WI_ASSERT guards on default switch cases in CompareByField ## Solution - Replace hardcoded SetCountLimit(6) with dynamic computation via GetAllExponentialEnumValues - Add SortField::None = 0x0 for bitmask initialization, move Relevance to 0x20, add Max = 0x40 sentinel - Extract ResolveSortParameters() into PackageTableSortHelper as a self-contained testable function - Replace HasAvailableVersion bool with std::optional<Version> throughout sort pipeline - Add WI_ASSERT(false) to default cases in both GetSortKey and CompareByField - Simplify EnsureListSortFieldCountMatchesLimit test to assert (1u << limit) == Max - Remove redundant ValidateArguments_StandardArgExceedsCountLimit test (covered by framework) - Add using-declaration for Settings namespace to reduce qualification noise ## How Validated - Full solution build (AppInstallerCLICore + AppInstallerCLITests): clean, zero warnings - All 19 sort-related test cases pass (199 assertions) - Spell check: no CI violations - End-to-end wingetdev deployment verified across 12 scenarios including settings, query, multi-sort, order direction, and invalid input edge cases

JohnMcPMS · 2026-05-08T16:36:36Z

    {
-        using Settings::SortField;
+        SortParameters result;
+        std::vector<SortField> sortFields;


nit: why not just use result.Fields directly?

If the answer is allowing [relevance] to be returned, I don't see a problem. It is true, and ShouldSort is what you expect anyone to look at first.

JohnMcPMS · 2026-05-08T16:45:56Z

+        }

+        // Resolve direction
+        SortDirection direction = SortDirection::Ascending;


nit: same here

For both of these it is more a style/preference thing as performance should be equivalent. I just personally like removing the 4 lines of code but I'm open to hearing about reasons not to. I can imagine a reason that is about first evaluating and then collecting the data independently for clarity. I can also imagine a NRVO type argument (although maybe this should be the constructor of SortParameters if that is a concern).

JohnMcPMS · 2026-05-08T16:48:17Z

+        const std::vector<SortField>& sortFields,
+        SortDirection direction)


const SortParameters&?

JohnMcPMS · 2026-05-08T16:48:58Z


        // Relevance-only means no sorting
-        if (sortFields.size() == 1 && sortFields[0] == Settings::SortField::Relevance)
+        if (sortFields.size() == 1 && sortFields[0] == SortField::Relevance)


sortParams.ShouldSort?

JohnMcPMS · 2026-05-08T16:53:37Z

+    //   hasQuery - whether a free-text query argument is present
+    //   hasExplicitAscending - whether --ascending was passed
+    //   hasExplicitDescending - whether --descending was passed
+    SortParameters ResolveSortParameters(


Why not be a constructor of SortParameters? You can leave the default constructor included as well if needed.

JohnMcPMS · 2026-05-08T16:58:45Z

            Argument{ Execution::Args::Type::IncludePinned, Resource::String::IncludePinnedInListArgumentDescription, ArgumentType::Flag},
            Argument::ForType(Execution::Args::Type::ListDetails),
-            Argument{ Execution::Args::Type::Sort, Resource::String::SortArgumentDescription, ArgumentType::Standard }.SetCountLimit(6),
+            Argument{ Execution::Args::Type::Sort, Resource::String::SortArgumentDescription, ArgumentType::Standard }.SetCountLimit(AppInstaller::GetAllExponentialEnumValues<Settings::SortField>(Settings::SortField::None).size()),


nit: There is probably a more efficient way that we could do this at compile time, like consteval size_t GetExponentialEnumValuesCount<Enum> that does the same algorithm just counting the number of items until we hit Max.

JohnMcPMS · 2026-05-08T17:02:00Z

I meant all of it. I don't see a reason to pessimistically split out the context/argument extraction from the resolution portion. If we expand to other commands, the arguments are likely to stay the same. Maybe certain fields are not valid and can be checked by those commands, but this shared portion should be able to stay unchanged.

JohnMcPMS · 2026-05-08T17:06:37Z

+            REQUIRE(actual[i].ParsedAvailableVersion.has_value() == expected[i].ParsedAvailableVersion.has_value());
            REQUIRE(actual[i].ParsedInstalledVersion == expected[i].ParsedInstalledVersion);
-            REQUIRE(actual[i].ParsedAvailableVersion == expected[i].ParsedAvailableVersion);
+            if (actual[i].ParsedAvailableVersion.has_value() && expected[i].ParsedAvailableVersion.has_value())


optional gives you all of these ParsedAvailableVersion checks at once through its equality operator.

This comment has been minimized.

Sign in to view

Madhusudhan-MSFT requested a review from JohnMcPMS April 29, 2026 21:20

Madhusudhan-MSFT changed the title ~~Implement sort logic for winget list output~~ Implement sort logic for winget list output Apr 29, 2026

Madhusudhan-MSFT marked this pull request as ready for review April 29, 2026 23:42

Madhusudhan-MSFT requested a review from a team as a code owner April 29, 2026 23:42

JohnMcPMS reviewed Apr 30, 2026

View reviewed changes

This was referenced Apr 30, 2026

Output of the upgrade command should be sorted alphabetically #1352

Open

[New Feature]: Customizable sorting for search output #1769

Open

Madhusudhan-MSFT force-pushed the user/masudars/list-sort-logic branch from d92410d to 5aae88f Compare May 1, 2026 21:01

Madhusudhan-MSFT requested a review from JohnMcPMS May 1, 2026 21:27

florelis reviewed May 6, 2026

View reviewed changes

Comment thread src/AppInstallerCLITests/Command.cpp Outdated

Comment thread src/AppInstallerCLITests/PackageTableSortHelper.cpp

Comment thread src/AppInstallerCLITests/PackageTableSortHelper.cpp Outdated

Madhusudhan-MSFT and others added 11 commits May 6, 2026 16:32

[ListSort, Workflow] Add sort logic for winget list output

49ae654

[ListSortTests, Refactor] Extract sort logic into testable header and…

a210423

… add comprehensive tests

[ListSort, SpellCheck] Add listsort to spelling expect list

813c8af

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[ListSort, Rename] Rename ListSortHelper to PackageTableSortHelper

0d86ce9

Rename to reflect broader scope — the helper sorts package table rows for any table-based command (list, search, upgrade), not just list.

Madhusudhan-MSFT and others added 3 commits May 6, 2026 16:32

Madhusudhan-MSFT force-pushed the user/masudars/list-sort-logic branch from e8ba2d5 to c19ce84 Compare May 6, 2026 23:34

Madhusudhan-MSFT requested a review from florelis May 6, 2026 23:46

florelis previously approved these changes May 7, 2026

View reviewed changes

JohnMcPMS reviewed May 7, 2026

View reviewed changes

Madhusudhan-MSFT dismissed florelis’s stale review via 4065b64 May 7, 2026 23:18

Madhusudhan-MSFT requested a review from JohnMcPMS May 7, 2026 23:21

JohnMcPMS reviewed May 8, 2026

View reviewed changes

		const std::vector<SortField>& sortFields,
		SortDirection direction)

Conversation

Madhusudhan-MSFT commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

⚠️ Behavior change: default sort order

Design decisions

How validated

Uh oh!

This comment has been minimized.

Trenly commented Apr 29, 2026

Uh oh!

Trenly commented Apr 29, 2026

Uh oh!

Madhusudhan-MSFT commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Madhusudhan-MSFT commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Trenly commented Apr 29, 2026

Uh oh!

JohnMcPMS commented Apr 29, 2026

Uh oh!

Madhusudhan-MSFT commented Apr 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Madhusudhan-MSFT commented Apr 29, 2026 •

edited

Loading

Madhusudhan-MSFT commented Apr 29, 2026 •

edited

Loading

Madhusudhan-MSFT commented Apr 29, 2026 •

edited

Loading