Powershell: New-Item: When creating symbolic links (symlinks) / reparse points, the -Target path should always be treated as a *literal* path

[mklement0]

Note:

• This is technically a breaking change, but one that to me falls into Bucket 3: Unlikely Grey Area.

• We've recently made an analogous change to Invoke-WebRequest / Invoke-RestMethod, which now sensibly interpret their -OutFile argument invariably as a _literal_ path - see #11701

  • Similar fixes are pending in other contexts: #4726, #9225, #4726.

Summary of the new feature/enhancement

When you create a symlink or reparse point, you want to target a _specific, literal_ target path - you're not looking for this path to determined via _wildcard-pattern matching_, which, however, is what currently happens: a -Target (-Value) argument is (invariably) interpreted as a wildcard pattern. What makes the behavior even less useful is that the pattern must resolve to _exactly one_ path.

• Interpreting the -Target (-Value) argument as a wildcard expression means that meant-to-be-literal paths such as [a].txt would mistakenly target a.txt, if present, for instance.

• Also, as a potentially unwanted side effect, if the -Target (-Value) _is_ determined via wildcard resolution, a relative input path (pattern) is invariably resolved to a _full_ path.

The sensible behavior is to _always_ treat the -Target (-Value) argument as a _literal_ path (and to preserve its relative-vs.-full path status, as specified).

---

Once the change is implemented, the following tests - which currently fail - should succeed:

$null = New-Item 'file1', 'file[1]'

$targetRelative = 'file[1]'
$targetAbsolute = Join-Path $pwd.providerpath 'file[1]'

(New-Item -Type SymbolicLink fileL -Target $targetRelative).Target | Should -Be $targetRelative
(New-Item -Force -Type SymbolicLink fileL -Target $targetAbsolute).Target | Should -Be $targetAbsolute

The tests currently fail, because file[1] is interpreted as a wildcard pattern that happens to match file1.

[SteveL-MSFT]

@PowerShell/powershell-committee agrees that -Target should have always have been a literal path and this is a bucket 3 breaking change

[JamesWTruher]

could you add a couple of actual examples please?

[iSazonov]

@mklement0 Please update title and description to follow "always".

[mklement0]

@iSazonov, done.
@JamesWTruher, I've added Pester tests to the bottom of the OP.

[iSazonov]

@mklement0 Are you ready to pull the fix? I'd review...

[mklement0]

@iSazonov, given that you're already familiar with that area of the code, how about we swap these roles? 😁

[iSazonov]

@mklement0 In the case we can not merge :-( without MSFT team but they are busy.

[mklement0]

Since I'm not familiar with the procedures: Are you saying that if you create the PR yourself, you cannot also merge it, but if I create it, you could? Wouldn't that mean that #13082 is also blocked until a maintainer has time to review and merge?

[iSazonov]

Yes, I can not merge my commit without anybody approve it. (It is good policy.) So I ask community members to pull PRs so that I can review and merge a community contribution if it is simple and well covered by tests without waiting MSFT experts.