"Best match" logic isn't clear at Microsoft Learn.

Brief description of your issue

Several folks have been confused about what happens when there is no exact match to a package.

The instructions at https://learn.microsoft.com/windows/package-manager/winget/install aren't clear enough.

Scenario 1
Users expect a command like winget install unzip to install a compression tool, but that's not what happens in the default state of WinGet when both the "msstore" and the "winget" community repository are configured.

The default query parameter "unzip" in this case is the search term used.

A case insensitive substring search is executed against each configured source with the intent of performing an install. In the case of the "msstore" source there is only one result returned. In the case of the "winget" source, no results are returned because the query parameter doesn't have any package where the substring has a case-insensitive match for the query string against any of the defined properties. Note that in this case a substring match is not sufficient to be treated as a "best match" result.

If only one result is returned as an effective match or the "best match" across all configured sources WinGet will install that package.

The behavior is different for the "Search" command. The search command will return all results from all configured sources including results that are not a candidate for a "best match". WinGet will perform the search across the "Name", "Id", "Moniker", and "Tags". In this case, the "msstore" source returns multiple results. The "winget" source also returns multiple results, and there is an indication of which field the match was found in.

Scenario 2
Users expect a command like winget install git to install the Git SCM tool.

In this case there is a single "best match" result from both the "winget" and the "msstore" source. Because there is more than one result, the user is prompted to disambiguate.

Additional detail
The WinGet Show command can help understand what would happen if the user were to run winget install <query> vs `winget search .

The results of winget show <query> can be used to understand what would happen if the command winget install <query> is executed. If multiple packages are found, the user is asked to disambiguate. If only one best result is returned, then the output shows a subset of the manifest including information about the publisher and the package as well as the installer that would be selected for the devices running the command. Sometimes different architecture and locale will suggest different installers based on the metadata contained in the package manifest.