Could Select-String -List be aliased to Select-String -First [$Num] ?

I was looking to stop searching a file after the first match, expecting Select-String -First 1.

Select-String | Select-Object -First 1 can stop the pipeline, and skip searching the rest of the file. This is fine, but later I found there is a parameter to Select-String which stops after the first match, and outputs the match information, it just has the not-obvious name -List (where did that come from?).

It is the only cmdlet in Core, Management, Utility modules with a -List parameter, difficult to guess what it does by analogy with other cmdlets. There are only two with a -First parameter (Select-Object and Import-CliXml), but one of them is used very often, so that’s probably what set my expectation.

Suggestion: could it be aliased to -First (and maybe -First $Num) for easier discoverability and easier guessing what it might do?

[KirkMunro]

The docs are poorly written.

List makes sense if it is explained properly. Something like this would be more appropriate:

Use -List to retrieve a list of input files whose contents match the regular expression. The first instance of text that matches the regular expression in each matching input file will be shown after the input file name.

[BrucePay]

As @KirkMunro points out, the detailed help is not exactly helpful as it appears to completely miss the point of this option. To amplify what he said, the point of -List is to list all of the files that contain the specified pattern. That’s why it’s -List and not -First. It returns the first match because it has to return something and the MatchInfo object has the file name it in it so why not. WRT aliases, they give another name to a parameter they don’t and can’t change it’s type. Adding a new -First N (and -Last N?) parameter would seem to be the way to go…