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

[HumanEquivalentUnit]

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?

[SteveL-MSFT]

The detailed help says:

-List [<SwitchParameter>]
        Indicates that the cmdlet returns only the first match in each input file. By default, `Select-String` returns a MatchInfo object for each match it finds.

I would agree that -List was a poorly chosen switch name. -First would make sense, but this is a switch and not a parameter so it doesn't take arguments which is different from Select-Object -First. It could be -FirstOne to make it more specific (perhaps slightly redundant...).

[vexx32]

I'd suggest maybe -FirstMatch or -FirstOnly?

[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..

[SteveL-MSFT]

cc @sdwheeler

[sdwheeler]

@SteveL-MSFT Can someone open a doc bug for this?