diff --git a/Docs/Cmdlets/Get-ChildItem2.md b/Docs/Cmdlets/Get-ChildItem2.md index dccbb2e..2db61e7 100644 --- a/Docs/Cmdlets/Get-ChildItem2.md +++ b/Docs/Cmdlets/Get-ChildItem2.md @@ -23,7 +23,7 @@ Get-ChildItem2 [[-Path] ] [[-Filter] ] [-Recurse] [-Directory] The `Get-ChildItem2` cmdlet lists the files and folders in the folders that you specify with `-Path`. It returns an `Alphaleonis.Win32.Filesystem.FileInfo` object for every file and an `Alphaleonis.Win32.Filesystem.DirectoryInfo` object for every folder. The cmdlet is the long-path counterpart of the built-in `Get-ChildItem` cmdlet: it enumerates the file system through the AlphaFS library (`Alphaleonis.Win32.Filesystem`) instead of `System.IO`, so it also returns items whose path is longer than the 260-character `MAX_PATH` limit. -If you omit `-Path`, the cmdlet lists the current location. Relative paths and the `.` and `..` notations are resolved against the current location. Each path must name a folder, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe folders from `Get-ChildItem2` or `Get-Item2` into another `Get-ChildItem2` call, and you can pipe the result into `Get-NTFSAccess` and the other NTFSSecurity cmdlets. +If you omit `-Path`, the cmdlet lists the current location. Relative paths and the `.` and `..` notations are resolved against the current location. Each path must name an existing folder or file, and wildcard characters are not supported. The parameter accepts pipeline input by value and by the property name `FullName`, so you can pipe folders from `Get-ChildItem2` or `Get-Item2` into another `Get-ChildItem2` call, and you can pipe the result into `Get-NTFSAccess` and the other NTFSSecurity cmdlets. By default the cmdlet returns the immediate content of each folder and omits hidden items. Use `-Recurse` to walk the whole tree, `-Depth` to limit how deep the recursion goes, `-Filter` to restrict the result by name, `-Directory` or `-File` to restrict it by item type, and `-Force`, `-Hidden`, `-System`, `-ReadOnly`, or `-Attributes` to restrict it by file attributes. @@ -142,7 +142,15 @@ Accept wildcard characters: False ### -Filter -Specifies a name pattern that an item must match to be returned. The pattern follows the wildcard rules that Windows PowerShell 5.1 applies to `Get-ChildItem -Filter`, in both editions, on the real name of the item, not its 8.3 short name: an asterisk matches a run of characters, a question mark matches one character that is not a dot (nothing where a dot or the end of the name follows), and a dot also matches nothing where only wildcards or the end of the pattern follow, so that `Report.*` also returns `Report`, which has no dot, and `*.*` returns every item. The match ignores case and is not affected by the culture of the session. Any other character stands for itself, including a bracket, so `Report[1].txt` returns the file of that name. PowerShell 7 deliberately differs here from the built-in `Get-ChildItem`, whose own `-Filter` returns nothing for a pattern that ends in a dot and returns every item for `*.?`; `Get-ChildItem2` follows the Windows PowerShell 5.1 rules in both editions instead. The default value is `*`, which returns every item, and an empty value also returns every item. The pattern is applied to the name of each item, not to its path, and during a recursive listing it restricts only the returned items; the cmdlet still descends into every subfolder. +Specifies a name pattern that an item must match to be returned. The pattern follows the wildcard rules that Windows PowerShell 5.1 applies to `Get-ChildItem -Filter`, in both editions, on the real name of the item, not its 8.3 short name. An asterisk stands for a run of any characters, and a question mark stands for one character that is not a dot, or for nothing where a dot or the end of the name follows. A dot stands for a literal dot, or for nothing where only wildcards or the end of the pattern follow. The match ignores case and is not affected by the culture of the session. Any other character stands for itself, including a bracket, so `Report[1].txt` returns the file of that name. + +For example, `Report.*` also returns the item `Report`, which has no dot. + +A pattern of an asterisk, a dot, and an asterisk returns every item, also an item without a dot in its name, as `Get-ChildItem` does for this pattern. + +PowerShell 7 deliberately differs here from the built-in `Get-ChildItem`: its own `-Filter` returns nothing for a pattern that ends in a dot, unless the character right before the dot is an asterisk, and it returns every item for a pattern of an asterisk, a dot, and one or two question marks. `Get-ChildItem2` follows the Windows PowerShell 5.1 rules in both editions instead, so these are deliberate differences from PowerShell 7's own `Get-ChildItem`. + +The default value is `*`, which returns every item, and an empty value also returns every item. The pattern is applied to the name of each item, not to its path, and during a recursive listing it restricts only the returned items; the cmdlet still descends into every subfolder. ```yaml Type: String @@ -319,7 +327,11 @@ Before 5.0.0, a `-Path` value that points to a file stopped the cmdlet with an ` Before 5.0.0, `-Filter` read a bracket as the start of a character class, so a file with brackets in its name, such as `Report[1].txt`, was not returned for its name, and a pattern of an asterisk, a dot, and an asterisk dropped the items without a dot in their names, most folders among them. -The cmdlet enumerates broadly and matches each name once, with the Win32 "DOS" wildcard rules that Windows PowerShell 5.1 applies to `Get-ChildItem -Filter`, in both editions (Decision 27, item 4): `Report.*` also returns `Report`, which has no dot, a pattern that ends in a dot returns the names without a dot, and an empty value returns every item, like `*`. PowerShell 7 itself differs from Windows PowerShell 5.1 here: its own `Get-ChildItem -Filter` returns nothing for a pattern that ends in a dot and returns every item for `*.?`. `Get-ChildItem2` follows the Windows PowerShell 5.1 rules in both editions instead of the edition it runs in, so this is a deliberate difference from the built-in `Get-ChildItem` in PowerShell 7 for these two pattern shapes. +The cmdlet enumerates broadly and matches each name once, with the Win32 "DOS" wildcard rules that Windows PowerShell 5.1 applies to `Get-ChildItem -Filter`, in both editions: a pattern that ends in a dot returns the names without a dot, and an empty value returns every item, the same as a plain asterisk. + +For example, `Report.*` also returns the item `Report`, which has no dot. A star in front of a dot token may cross every dot in the name but the last one, so a pattern such as a star followed by a dot also reaches the final segment of a name with two or more dots, for example `archive.tar.gz`. + +PowerShell 7 itself differs from Windows PowerShell 5.1 here: its own `Get-ChildItem -Filter` returns nothing for a pattern that ends in a dot, unless the character right before the dot is an asterisk, and it returns every item for a pattern of an asterisk, a dot, and one or two question marks. `Get-ChildItem2` follows the Windows PowerShell 5.1 rules in both editions instead of the edition it runs in, so this is a deliberate difference from the built-in `Get-ChildItem` in PowerShell 7 for these pattern shapes. Before 5.0.0, a `break`, a `continue`, or a `throw` in a later command of the pipeline did not end the cmdlet for an item below the first folder, also when the later command took the error of a folder that the cmdlet cannot read, for example with `2>&1`. diff --git a/Tests/ItemCmdlets.Tests.ps1 b/Tests/ItemCmdlets.Tests.ps1 index 5c26da8..e610a82 100644 --- a/Tests/ItemCmdlets.Tests.ps1 +++ b/Tests/ItemCmdlets.Tests.ps1 @@ -250,7 +250,7 @@ Describe 'Get-ChildItem2' { ($result.Name | Sort-Object) -join ',' | Should -BeExactly 'NoExtension,NoExtensionFolder,Page.htm' } - # The cmdlet now has one matcher, not two (Decision 27, item 4): every dot in -Filter whose single next + # The cmdlet now has one matcher, not two: every dot in -Filter whose single next # character is an asterisk or a question mark, or that has nothing after it, is a DOS_DOT, and *.*.* has # two such dots, so it returns every item, the same as *.* and a plain *. Before this change, the cmdlet # compared the name with the pattern a second time with the dots read as ordinary characters, so only a @@ -269,7 +269,7 @@ Describe 'Get-ChildItem2' { } # The names are matched once, by the cmdlet, with the Win32 "DOS" wildcard rules that Windows PowerShell 5.1 - # applies to Get-ChildItem -Filter, in both editions (Decision 27, item 4): Report.* also returns Report, + # applies to Get-ChildItem -Filter, in both editions: Report.* also returns Report, # which has no dot, and a trailing dot asks for the names without a dot. Report* is the control: without a # dot in the pattern, the names with and without a dot are both returned, as before. It 'Should return for -Filter ""' -ForEach @(