Say that a list for -AccessType or -AppliesTo lets one of the values win
silently or, for -AppliesTo, selects a scope that nobody named (the sum of
two Allow and Deny numbers is always one of the two), and that every kind of
collection counts. State the third edge case of Get-ChildItem2 -Filter (blanks
at the end of the pattern, also before a final dot), limit the error of
Windows PowerShell 5.1 to an even number of dots at the end, and name the
pattern of a single dot, for which the built-in filter of PowerShell 7
returns every item. The help file is regenerated, and the pages and the file
are a fixpoint after a rebuild.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Say in the pages and in the CHANGELOG what a script block, a named $null of
-AppliesTo, a list for -AccessType or -AppliesTo, and a piped value that
PowerShell cannot convert did before 5.0.0 and do now; name the carry-over of
the scope between piped descriptors for the objects that it affected; mark
the descriptor sets that go on after a failing descriptor and the checks of
the object with both parameter groups as breaking, with the hint that a
script that relied on the stop needs -ErrorAction Stop.
Describe where Get-ChildItem2 -Filter differs from the built-in filter of
PowerShell 7 with the shapes that really differ (a pattern that ends in a dot,
an asterisk followed by a dot and question marks) and state the two cases that
are not like Windows PowerShell 5.1: a blank at the end of the pattern is part
of it, and a pattern that ends in two dots is accepted.
The pages and the help file are a fixpoint again after a rebuild.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Regenerate NTFSSecurity.dll-Help.xml from the pages with New-ExternalHelp
and let platyPS wrap the syntax of the four add and remove pages for the
parameters that are Object now. The pages and the file are a fixpoint: after
a rebuild, Update-MarkdownHelp changes no page and New-ExternalHelp changes
no file.
State two sentences more plainly: what a blank value of the other parameter
group does to the four add and remove cmdlets, and where Get-ChildItem2
-Filter differs from the built-in Get-ChildItem in PowerShell 7.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
An independent review found that platyPS 0.14.2, which generates the
shipped help file from these pages, pairs up every two literal
asterisks within one paragraph as markdown emphasis and drops them,
even inside backticks: the -Filter parameter description and the
matching paragraph of NOTES each had three or four literal asterisks
in one paragraph, so `Get-Help Get-ChildItem2 -Parameter Filter` and
the NOTES section showed `Report. ` instead of `` Report.* `` and
` . ` instead of a plain asterisk pattern, silently losing the
character that the sentence was about.
Both paragraphs are now several short paragraphs, each with at most
one literal asterisk; a pattern that itself needs more than one
asterisk, such as a plain asterisk, a dot, and an asterisk, is spelled
out in words instead, the way the page already did before this
feature. Verified by running `New-ExternalHelp` from platyPS 0.14.2
into a temporary folder (not the repository's help file) and
confirming every pattern renders intact in the generated XML, then
removing the folder.
The same two paragraphs also said PowerShell 7's own `Get-ChildItem
-Filter` returns nothing for any pattern that ends in a dot and
returns every item only for a pattern of an asterisk, a dot, and one
question mark. Measured directly on PowerShell 7.6.7, both overstated
the difference: a trailing dot returns nothing there only when the
character right before the dot is not an asterisk (a star right
before the dot behaves the same as Windows PowerShell 5.1 and as
Get-ChildItem2 there too), and a pattern of an asterisk, a dot, and
two question marks also returns every item, not only one question
mark. Both paragraphs now say exactly that.
Also removed "(Decision 27, item 4)" from both paragraphs and from two
test comments (the maintainer's agent already removed it from the
integration branch; this avoids a conflicting edit), and changed one
sentence of the DESCRIPTION section that said every -Path value must
name a folder: a value that names a file returns that file, as the
PARAMETERS section and NOTES already said and the cmdlet already did.
No test changes: these are documentation wording changes only, and the
page keeps its existing structure (headings, parameter block, NOTES
list). Re-ran Tests\ItemCmdlets.Tests.ps1 (no code changed in this
commit) to confirm the suite is still green: elevated-Desktop
193/0/0, elevated-Core 192/0/1, basic-Desktop 187/0/6, basic-Core
186/0/7 (passed/failed/skipped), three times, identical.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Get-ChildItem2 -Filter now applies a single matcher, in the cmdlet, that
follows the Win32 "DOS" wildcard rules Windows PowerShell 5.1 applies to
Get-ChildItem -Filter, on the real name of the item, in both editions
(Decision 27, item 4, option B). Before this change the pattern was
matched twice: once by the AlphaFS enumeration and once by the cmdlet
with a WildcardPattern that read a dot as an ordinary character, so the
two editions, and Get-ChildItem itself, disagreed on patterns with a
dot. AlphaFS now always enumerates with "*", and the new matcher decides
alone.
What a user sees changing:
- "Report.*" also returns "Report", which has no dot (previously only
names with a dot matched a pattern ending in ".*").
- A pattern that ends in a dot, such as "Report." or "Rep*.", now
returns the names without a dot, instead of nothing.
- "*.*.*" now returns every item, the same as "*.*" and a plain "*",
instead of only names with two literal dots.
- Breaking: an empty -Filter ('') now returns every item, like no
filter at all, instead of nothing. This matches the policy of
Windows PowerShell 5.1 for every other dot pattern; a script that
relied on an empty -Filter returning nothing should pass -Filter '*'
explicitly to keep that behavior from before.
- A single dot ('.') as -Filter also returns every item, matching
Get-ChildItem.
- Get-ChildItem2 deliberately no longer follows PowerShell 7's own
Get-ChildItem -Filter for a pattern that ends in a dot (which there
returns nothing) or for "*.?" (which there returns every item): it
follows the Windows PowerShell 5.1 rules in both editions instead, so
the two editions of Get-ChildItem2 agree with each other.
- Unaffected: -Filter matching by the real name and not the 8.3 short
name, brackets and backticks as ordinary characters, case-insensitive
matching with the invariant culture, the null-Filter error, and every
other parameter and its interaction with -Filter.
The matcher was derived and checked against a differential oracle of
real Windows PowerShell 5.1 Get-ChildItem -Filter runs: two independent
sets of 8.3-compliant names (22 and 19 names) against 54,654 generated
patterns each (alphabet a, b, c, ., *, ? up to length 6; the remaining
1,333 of the 55,987 generated patterns per set are refused by the .NET
enumeration API itself for ending in ".." and are not part of either
product's -Filter semantics), with zero differences in both sets.
Tests (Tests\ItemCmdlets.Tests.ps1, "Get-ChildItem2" > "Recursion, type
filters, and depth"):
- Changed the dot-rules table (pins the new values for "Report.*",
"Report.", "Rep*.", "*.", and an empty -Filter) and the dedicated
"*.*.*" test (now expects every item), both of which pinned the old,
changed-on-purpose behavior.
- Added three rows to the existing short-name-sensitive test, to pin
that the new matcher still reads the real name, not the short name,
for the trailing-dot and "X.*" rule families.
- Added a 36-row truth table (22 fixed 8.3-compliant names, patterns
from every family the WI calls out) with the literal result of
Windows PowerShell 5.1 as static, hand-verified data; the test runs
no Get-ChildItem of its own.
- Added -Recurse with a selective -Filter across three folder levels,
a dot -Filter with -File and -Directory, an empty -Filter, and a
-Filter on a -Path that names a file.
Docs\Cmdlets\Get-ChildItem2.md: restated the -Filter parameter
description and the matching note in NOTES with the Windows PowerShell
5.1 policy and the deliberate PowerShell 7 difference, and removed the
sentences that described the dot rules as a limitation or a mismatch
with Get-ChildItem in Windows PowerShell 5.1.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The comment above the recording Write methods of BaseCmdlet named three
cmdlets that call ShouldProcess in a try block; only Remove-Item2 does.
The Get-ChildItem2 page now says that the dot rules of the matching can
differ, not that they differ, and the generated help follows. No test and
no executable code changes.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The cmdlet page said that the AlphaFS enumeration alone decides which names match, while the code compares each returned name with the pattern again; both apply, and the page now says so. The comment of PipelineControl said that every Write method is noted, but WriteWarning is not, and it names ShouldProcess as an example of an unnoted call. The changelog entries about the privileges name the cmdlets that enable them for the duration of their command, because Enable-Privileges keeps them enabled by design.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Get-ChildItem2 swallowed what a later command threw for the error of a nested folder, for example `Get-ChildItem2 -Recurse 2>&1 | ForEach-Object { throw 'x' }`: the recursion took it for a failure of the folder above, wrote a verbose message, and left the loop over the folders, so the listing ended early and the caller never saw the exception. BaseCmdlet now notes the exception that WriteError raises, as it does for WriteObject, WriteVerbose, and WriteDebug. The report that -ErrorAction Stop is swallowed there too was not reproducible (the error reaches the caller), and a break or Select-Object -First was already passed on by type; the tests keep both.
A cmdlet that enables the privileges wrote the debug message "..enabled" before it noted the privilege, so a later command that ended the pipeline or threw at that message left the privilege enabled: Dispose disables only what is noted. TryEnablePrivilege also took the exception of a later command for a failure to enable the privilege and went on with the next one, so `Get-NTFSOwner 5>&1 | ForEach-Object { if ($_.Message -eq '..enabled') { throw 'x' } }` enabled all four privileges and hid the exception. The privilege is noted before the message, and TryEnablePrivilege passes the exception on.
Red before the fix in the Release build of 7aa8315: three tests (the throw on the error stream, in four configurations the first, in the two elevated ones the two privilege tests). Also covers the typed-throw rows that fail if PowerShell stops wrapping a thrown exception, and Enable-Privileges in a script named NTFSSecurity.Init.ps1.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
A throw in a later command, or an error with -ErrorAction Stop, reaches a cmdlet through its Write call as an ordinary exception. The catch for the failures of an item reported it as the error of that item and went on, so that Remove-Item2 -PassThru removed the next item after a throw, and the caller never saw the exception. The earlier check found only the end of the pipeline and a break or continue. BaseCmdlet now notes the exception that its WriteObject, WriteVerbose, and WriteDebug raised, and every catch that can enclose a write passes it on; Get-DiskSpace writes outside its try. Set-NTFSSecurityDescriptor and Get-FileHash2 also caught it at a verbose message.
Get-ChildItem2 -Filter *.* returns every item, as Get-ChildItem does. The cmdlet compared each name with the pattern again and dropped the items without a dot, most folders among them; the dot stays an ordinary character in other patterns.
The failed lookup of InheritedFrom frees its native buffer. The help paragraph of -Filter has no pair of asterisks, which platyPS turns into emphasis, and the page has an example for *.*.
Review of the independent pass: the restored-owner test asserts that a plain write is denied, the drive-mapping helper has guard tests and takes letters that the no-volume tests do not, and the pipeline tests cover a throw, an error with -ErrorAction Stop, and the verbose and debug streams for every cmdlet that can reach the code.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The escape of brackets in the pattern read the filter before the pattern could reject it, so a null filter ended in a NullReferenceException. The parameter now rejects null with a validation error that names it; an empty filter still matches no item.
The cmdlet compares each name that the enumeration returns with the pattern again. The two disagree for *.*: the enumeration returns every item, as Get-ChildItem does, and the comparison drops the names without a dot, files and folders alike. A test pins this and reaches the branch that drops an item; the help says that a dot is an ordinary character.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
The cmdlet compares the name of every item that the enumeration returns with the pattern again, and it built that comparison with the wildcard syntax of PowerShell. A bracket then began a character class, so Report[1].txt was returned by the enumeration, which treats a bracket as itself, and dropped by the comparison, and a file with brackets in its name could not be found for its name with -Filter, which Get-ChildItem does. The documentation names only * and ? as wildcards, so a bracket and a backtick now stand for themselves in the comparison.
The regression test fails without the fix in all four configurations. The probe also showed that AlphaFS compares only the long name, so the test for *.htm guards the documented contract and no 8.3 behavior. The page of the cmdlet names the rule and the help file is generated again.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
An empty Get-ChildItem2 -Attributes value, such as 0 or None in
PowerShell 7, matched every item and returned hidden items as well; it now
stops the cmdlet with AttributesEmpty, as Get-ChildItem rejects it. The page
says that the + and ! operators of Get-ChildItem aren't supported and that
-Recurse still enters hidden folders, and the changelog says that a call
with several attributes now returns more items. The type data test starts
Windows PowerShell, where the import failed, from both CI legs and checks
that LengthOnDisk is still there.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Get-ChildItem2 -Attributes returned only the items that had all the listed
attributes, so -Attributes Hidden, ReadOnly returned nothing where
Get-ChildItem returns both kinds of items. It now returns the items that have
any of them (#5).
BREAKING CHANGE: to get only the items with all the listed attributes,
filter the result with Where-Object, as the cmdlet page shows.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Security review of this branch, Major findings:
- M4: Get-NTFSAudit took ownership of an item whose SACL it couldn't
read. Ownership grants no access to the SACL, so the retry always
failed, and it left the owner changed. The cmdlet now writes a
ReadSecurityError with the category PermissionDenied, as Get-NTFSOwner
does since defect 9; the page says so.
- M1: Remove-TestSandbox reset the ACLs recursively before it removed the
links. Measured: icacls /reset /T did not follow the junction (the
target's explicit entry stayed), but the links now go first anyway; a
folder that denies listing gets a reset without /T. New test: the ACL
of a junction target stays unchanged.
- m4: Assert-TestSandboxPath now rejects a path below a link, which can
point outside the sandbox (new test, failed before).
- M5: the Inherits column reads one ACL per displayed item; the
Get-ChildItem2 page names the cost and how to avoid it.
- M2: the comment of the CI-only Get-NTFSAudit repeat test states what it
guards; Access.Tests.ps1 guards the same loop fix without elevation.
- M3, the stale hash of Get-FileHash2, is fixed on ai/defects-c.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Defect 13. The Inherits column of the Children2 view, which formats the
Get-ChildItem2 output, negated the IsInheritanceBlocked property. The
module defines that property for System.IO.FileInfo and DirectoryInfo
only, not for the AlphaFS objects that Get-ChildItem2 returns, so the
column showed !$null, that is True, for every item. The view now reads
the protection of the DACL from the item.
Tests/ItemCmdlets.Tests.ps1: 2 tests on the formatted output.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Defect 2. Get-ChildItem2 cast every -Path item to DirectoryInfo, so a file
path stopped the cmdlet with an InvalidCastException, a terminating error
that also skipped the remaining paths. Like Get-ChildItem, a file path now
returns the file itself, filtered like the other items; with -Directory it
returns nothing.
Tests/ItemCmdlets.Tests.ps1 (new): 3 tests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* chore: initialize the memory bank
Add the canonical .memory-bank base with evidence-based project context:
purpose and scope, workflows, stack and validation commands, architecture
map, decisions, and the open work found while documenting the cmdlets.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* docs: align documentation with the cmdlet source
- Fill all 36 platyPS cmdlet pages from the C# source: synopsis,
description, parameters, defaults, examples, inputs, outputs, and
notes, including documented limitations of the current code
- Check every example against live parameter metadata and run them in a
sandbox; fix examples that did not work (CSV restore, account filter,
recursive inheritance, -AccessRights typos)
- Rewrite the home, concepts, examples, README, and contributor pages;
add a grouped cmdlet overview, module settings, privileges, long paths,
and the platyPS workflow
- Document Remove-Item2 -PassThru as renamed after 4.2.6 (#64)
- Fix mkdocs.yml navigation, edit_uri, and copyright markup; add
build.os and a pinned MkDocs version for Read the Docs
- Point online help links to the pages on GitHub; add CHANGELOG.md
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* ci: build the module and check the docs against the build
The documentation check ran Update-MarkdownHelp against the NTFSSecurity
release from the PowerShell Gallery (4.2.6), so it failed for every
unreleased parameter change. PR #91 failed because 4.2.6 still has
Remove-Item2 -PassThur while the source and the docs have -PassThru.
- Build NTFSSecurity.csproj in Release on the Visual Studio 2022 image,
using the .NET Framework 4.5.2 reference assemblies package instead of
an installed targeting pack
- Check Docs/Cmdlets against the module built from source
- Pin platyPS 0.14.2 and MarkdownLinkCheck 0.2.0, and enable TLS 1.2 so
the NuGet provider bootstrap works
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
* chore: record the green PR 91 build in the memory bank
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>
Raimund Andree
sup3rlativ3