Fixes #12812 - Add note to -Path about duplicate filename handling

[sdwheeler]

PR Summary

Add note to -Path about duplicate filename handling

• Fixes AB#558680
• Fixes Need more clarity on -Path argument for New-FileCatalog #12812

PR Checklist

• Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• Summary: This PR's summary describes the scope and intent of the change.
• Contributor's Guide: I have read the contributor's guide.
• Style: This PR adheres to the style guide.

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[Copilot]

Pull request overview

Updates the New-FileCatalog reference docs to clarify how -Path behaves when given multiple, unrelated file/folder paths—specifically around relative path generation and duplicate filename collisions.

Changes:

• Expands -Path parameter description to mention recursive enumeration and relative paths in the catalog.
• Adds an IMPORTANT note explaining why duplicate filenames can be problematic when passing a list of paths and recommends passing a single root folder.
• Updates ms.date in affected versions (5.1, 7.4, 7.5, 7.6).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
reference/7.6/Microsoft.PowerShell.Security/New-FileCatalog.md	Adds IMPORTANT guidance for -Path list behavior and updates parameter text/date.
reference/7.5/Microsoft.PowerShell.Security/New-FileCatalog.md	Same clarification for PowerShell 7.5 docs.
reference/7.4/Microsoft.PowerShell.Security/New-FileCatalog.md	Same clarification for PowerShell 7.4 docs.
reference/5.1/Microsoft.PowerShell.Security/New-FileCatalog.md	Same clarification for Windows PowerShell 5.1 docs.

Comments suppressed due to low confidence (4)

reference/7.6/Microsoft.PowerShell.Security/New-FileCatalog.md:103

• The phrase "only uses the filename for the hash" is misleading/inaccurate: the cryptographic hash is for the file contents, not derived from the filename. Consider rewording to say the cmdlet uses only the filename as the catalog entry identifier/path key (so duplicate names from different locations collide) while still hashing file contents.

> When you provide a list of files or folders, the cmdlet can't compute a relative path since the
> files and folders can be anywhere on the filesystem. Under this condition, the cmdlet only uses
> the filename for the hash, which means that you can't have duplicate filenames in different paths.
> For the best results, pass in a single folder and let the cmdlet enumerate the contents. The

reference/7.5/Microsoft.PowerShell.Security/New-FileCatalog.md:103

• The phrase "only uses the filename for the hash" is misleading/inaccurate: the cryptographic hash is for the file contents, not derived from the filename. Consider rewording to say the cmdlet uses only the filename as the catalog entry identifier/path key (so duplicate names from different locations collide) while still hashing file contents.

> When you provide a list of files or folders, the cmdlet can't compute a relative path since the
> files and folders can be anywhere on the filesystem. Under this condition, the cmdlet only uses
> the filename for the hash, which means that you can't have duplicate filenames in different paths.
> For the best results, pass in a single folder and let the cmdlet enumerate the contents. The

reference/7.4/Microsoft.PowerShell.Security/New-FileCatalog.md:103

• The phrase "only uses the filename for the hash" is misleading/inaccurate: the cryptographic hash is for the file contents, not derived from the filename. Consider rewording to say the cmdlet uses only the filename as the catalog entry identifier/path key (so duplicate names from different locations collide) while still hashing file contents.

> When you provide a list of files or folders, the cmdlet can't compute a relative path since the
> files and folders can be anywhere on the filesystem. Under this condition, the cmdlet only uses
> the filename for the hash, which means that you can't have duplicate filenames in different paths.
> For the best results, pass in a single folder and let the cmdlet enumerate the contents. The

reference/5.1/Microsoft.PowerShell.Security/New-FileCatalog.md:100

• The phrase "only uses the filename for the hash" is misleading/inaccurate: the cryptographic hash is for the file contents, not derived from the filename. Consider rewording to say the cmdlet uses only the filename as the catalog entry identifier/path key (so duplicate names from different locations collide) while still hashing file contents.

> When you provide a list of files or folders, the cmdlet can't compute a relative path since the
> files and folders can be anywhere on the filesystem. Under this condition, the cmdlet only uses
> the filename for the hash, which means that you can't have duplicate filenames in different paths.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[learn-build-service-prod]

Learn Build status updates of commit a2f5641:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Security/New-FileCatalog.md	✅Succeeded	View (powershell-5.1)
reference/7.4/Microsoft.PowerShell.Security/New-FileCatalog.md	✅Succeeded	View (powershell-7.4)
reference/7.5/Microsoft.PowerShell.Security/New-FileCatalog.md	✅Succeeded	View (powershell-7.5)
reference/7.6/Microsoft.PowerShell.Security/New-FileCatalog.md	✅Succeeded	View (powershell-7.6)

For more details, please refer to the build report.