Add -Extension parameter to Join-Path cmdlet #26482

yotsuda · 2025-11-19T00:17:56Z

PR Summary

This PR adds a new -Extension parameter to Join-Path cmdlet that allows changing the file extension of the resulting path, providing parity with Split-Path's extension handling capabilities.

Fixes #20724

PR Context

The Split-Path cmdlet has an -Extension parameter that retrieves the file extension from a path. However, Join-Path lacks the ability to set or change extensions when joining paths. This enhancement adds an -Extension string parameter to Join-Path that modifies the extension of the final joined path.

Changes

Modified CombinePathCommand.cs: Added -Extension parameter with ValueFromPipelineByPropertyName support
Uses System.IO.Path.ChangeExtension() to modify the extension
Handles empty string extension by removing the trailing dot for cleaner output
Added 6 test cases in Join-Path.Tests.ps1

Testing

New tests added:

"should change extension when -Extension parameter is specified"
"should add extension to file without extension"
"should remove extension when empty string is specified"
"should change extension for multiple paths"
"should handle extension with or without leading dot"
"should accept Extension from pipeline by property name"

Examples:

# Change extension
Join-Path -Path "C:\folder" -ChildPath "file.txt" -Extension ".log"
# Output: C:\folder\file.log

# Add extension
Join-Path -Path "C:\folder" -ChildPath "file" -Extension ".txt"
# Output: C:\folder\file.txt

# Remove extension
Join-Path -Path "C:\folder" -ChildPath "file.txt" -Extension ""
# Output: C:\folder\file

# Pipeline input
[PSCustomObject]@{ Path = "C:\folder"; ChildPath = "file.txt"; Extension = ".log" } | Join-Path
# Output: C:\folder\file.log

Test results:

All 6 new tests pass
All existing tests continue to pass

PR Checklist

PR has a meaningful title
- Use the present tense and imperative mood when describing your changes
Summarized changes
Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
This PR is ready to merge. If this PR is a work in progress, please open this as a Draft Pull Request and mark it as Ready to Review when it is ready to merge.
Breaking changes
- None
User-facing changes
- Documentation needed
  - New -Extension parameter should be documented in Join-Path cmdlet help Document new -Extension parameter for Join-Path cmdlet MicrosoftDocs/PowerShell-Docs#12535
Testing - New and feature
- Make sure you've added a new test if existing tests do not effectively test the code changed

This adds a new -Extension parameter to Join-Path that allows changing the file extension of the resulting path, providing parity with Split-Path's extension handling capabilities. Features: - Change extension: Join-Path -Path C:\folder -ChildPath file.txt -Extension .log - Add extension: Join-Path -Path C:\folder -ChildPath file -Extension .txt - Remove extension: Join-Path -Path C:\folder -ChildPath file.txt -Extension '' - Supports pipeline input via ValueFromPipelineByPropertyName Fixes PowerShell#20724

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs

Copilot

Pull Request Overview

This PR adds a new -Extension parameter to the Join-Path cmdlet, enabling users to modify file extensions when joining paths. This provides parity with Split-Path's extension handling and eliminates the need for separate extension manipulation after path joining.

Key changes:

Added -Extension parameter with pipeline by property name support to JoinPathCommand
Implemented extension modification using System.IO.Path.ChangeExtension with special handling for empty string extensions
Added 6 test cases covering basic extension operations and pipeline input

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs	Adds the `-Extension` parameter property and implements the extension change logic in `ProcessRecord()` after path joining but before resolution
test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1	Adds 6 test cases covering extension change, addition, removal, multiple paths, dot handling, and pipeline input

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

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

…nt/CombinePathCommand.cs Co-authored-by: Copilot <[email protected]>

- Use string.TrimEnd('.') instead of Substring for cleaner code - Remove redundant EndsWith check - Add tests for multiple dots, directory-like paths, and multiple child paths

Copilot

Pull Request Overview

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

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

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs

…nt/CombinePathCommand.cs Co-authored-by: Copilot <[email protected]>

Use $SepChar variable instead of hardcoded backslashes in test expectations to ensure tests pass on both Windows and Unix platforms.

Copilot

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

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

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

iSazonov · 2025-11-20T04:06:07Z

@brianary Please review.

iSazonov · 2025-11-20T04:08:52Z

@yotsuda Please open new issue in https://github.com/MicrosoftDocs/PowerShell-Docs

GitHub
GitHub - MicrosoftDocs/PowerShell-Docs: The official PowerShell documentation sources
The official PowerShell documentation sources. Contribute to MicrosoftDocs/PowerShell-Docs development by creating an account on GitHub.

iSazonov · 2025-11-20T04:13:08Z

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs

+                    // Remove trailing dot when extension is empty string
+                    if (Extension.Length == 0)
+                    {
+                        joinedPath = joinedPath.TrimEnd('.');
+                    }


@mklement0 What is your opinion about this?

@yotsuda Have we test for the code path?

@iSazonov Yes, this code path is tested at line 95-97 in Join-Path.Tests.ps1.

However, I'm considering adding another test case to document the behavior of TrimEnd('.') with multiple trailing dots (e.g., file..txt → file). This would clarify the intentional difference from the original Substring approach.

Should I add this test, or is the current coverage sufficient?

@yotsuda Lets wait @mklement0 feedback.

Technically, it amounts to a deviation from the underlying .NET API, because [io.path]::ChangeExtension('x.txt', '') yields 't.', i.e. retains the trailing .; by contrast, the trailing . is removed if you pass a true null ([io.path]::ChangeExtension('x.txt', [nullstring]::value)).

That said, making a '' argument exhibit the latter behavior - i.e. removal of the (last) extension - makes more sense to me, not least because you cannot really files with names that end in . on Windows (the trailing . is in effect ignored; not on Unix-like platforms, though).

The simpler and more robust implementation, though, is to simply translate the empty string to null and let .ChangeExtension() deal with it - it only removes the last extension present, and each lone . is considered its own extension; e.g. [io.path]::ChangeExtension('x...', [nullstring]::value) yields 'x..'.

Note that if we wanted to be consistent with .NET, users would have to - awkwardly - pass ([NullString]::Value) as the -Extension argument in order to achieve extension removal.

-Extension [NullString]::Value effectively ignore the parameter.

-Extension [NullString]::Value would pass verbatim [NullString]::Value as the parameter value, so I assume you mean -Extension ([NullString]::Value)
Yes, the current code ignores a null value, so IF we wanted to support that, we'd have to modify that - but I don't think we should.

To summarize what I'm suggesting:

Prevent passing null (both [NullString]::Value and $null) as the parameter value, which is consistent with what most cmdlets with [string] parameters do.

Translate "" as an argument value to null when calling .ChangeExtension(), resulting in removal of the (last) extension.

Document that "." must be passed in order to retain the (last) trailing .

To spell it out:

Inside the if (Extension != null && joinedPath != null) branch, the only code should be:

joinedPath = System.IO.Path.ChangeExtension(joinedPath, Extension.Length == 0 ? null : Extension);

Plus, the Extension parameter property must be declared not to accept null, though I'm confused about that: I thought that is the case by default and that you must conversely opt in to support null, via [AllowNull()]. However, in quick tests it seems that null is accepted by default. So perhaps a [ValidateNotNull] attribute is needed too.

@mklement0 Thank you for the review! I've simplified the code as suggested in 9b084f2:

joinedPath = System.IO.Path.ChangeExtension(joinedPath, Extension.Length == 0 ? null : Extension);

Question about [ValidateNotNull]: When -Extension "" is specified, we internally pass null to ChangeExtension(). However, this is unrelated to the behavior when -Extension $null is passed (or when -Extension is not specified at all). Therefore, the [ValidateNotNull] attribute doesn't seem necessary, but please let me know if it is indeed required.

I've also added test cases for preserving dots in base names ("file...txt" → "file.." when removing, "file...txt" → "file...md" when changing).

Thanks, @yotsuda.

The goal is to ensure that neither -Extension $null nor -Extension ([NullString]::Value) are accepted.

If this is already the case: great.
If not, [ValidateNotNull] is needed.

(As noted, I'm unclear on whether the non-null constraint is enforced by default or not.)

brianary

Looks great!

kilasuit · 2025-11-20T22:19:57Z

Minor brief comment from inital look at this PR's intent.

I feel there's no real need for the . to be passed in the extension as logically I'd expect that if you are passing -extension ".txt" for the actual extension to be ..txt or a more common scenario -extension "tar.gz" for a TAR compressed archive with gz like myarchive.tar.gz but we should ensure this PR allows people to have code that allows for both -extension "tar.gz" & -extension ".tar.gz" to work with no unintended consequences & documented that we do this purposefully to protect from accidental ..tar.gz extensions and the like.

So if that scenario works too, I'll be more than happy with this being added.

mklement0 · 2025-11-20T22:39:07Z

@kilasuit, yes, a leading . is tolerated by the underlying .NET API, so that -Extension .tar.gz and -Extension tar.gz can be used interchangeably; e.g., both [io.path]::ChangeExtension('x.txt', 'tar.gz') and [io.path]::ChangeExtension('x.txt', '.tar.gz') yield 'x.tar.gz'

- Simplify extension logic: use ternary operator to pass null when empty - Remove TrimEnd('.'): fixes issue where dots in base name were removed - Add test cases for preserving dots in base name: * When removing extension (file...txt -> file..) * When changing extension (file...txt -> file...md)

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs

iSazonov · 2025-11-21T04:26:49Z

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

+  It "should change extension when -Extension parameter is specified" {
+    $result = Join-Path -Path "folder" -ChildPath "file.txt" -Extension ".log"
+    $result | Should -BeExactly "folder${SepChar}file.log"
+  }
+  It "should add extension to file without extension" {
+    $result = Join-Path -Path "folder" -ChildPath "file" -Extension ".txt"
+    $result | Should -BeExactly "folder${SepChar}file.txt"
+  }


We can use TestCases for all tests.

Also I'd add cases - extension without dot ("txt"), double extension (".tar.gz", "tar.gz")

Thank you for the review! I've refactored the tests to use TestCases and added the requested test cases for extension without dot ("txt") and double extensions (".tar.gz", "tar.gz") in f06c5bc.
All tests pass.

…nt/CombinePathCommand.cs Co-authored-by: Ilya <[email protected]>

@iSazonov

- Consolidate individual extension tests into TestCases for better maintainability - Add test cases for extension without leading dot ('txt') - Add test cases for double extensions ('.tar.gz', 'tar.gz') - Remove duplicate test that is now covered by TestCases Addresses review feedback from @iSazonov

@iSazonov

- Add [ValidateNotNull] attribute to prevent explicit null values - Update XML comment to clarify default behavior when Extension is not specified Addresses review feedback from @iSazonov

iSazonov · 2025-11-21T17:36:14Z

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

+      Path = "folder"
+      ChildPath = "file.txt"
+      Extension = ".log"
+      ExpectedResult = "folder${SepChar}file.log"


For readability I'd simplify these cases.
Path is the same in all tests so I believe we can remove it here and use directly in test body.
ExpectedResult I'd rename to ExpectedChildPath, leave only file name with new extension and build the full value in test body.:

Suggested change

ExpectedResult = "folder${SepChar}file.log"

ExpectedChildPath = "file.log"

@iSazonov Updated in 6096b84. Simplified TestCases as suggested - removed constant Path, renamed ExpectedResult to ExpectedChildPath, and build full path in test body. Thank you!

@iSazonov

- Remove Path from TestCases as it's constant across all tests - Rename ExpectedResult to ExpectedChildPath for clarity - Build full path in test body using 'folder' directly Addresses review feedback from @iSazonov

yotsuda · 2025-11-22T01:42:02Z

@iSazonov Thank you for the guidance. I've opened an issue in PowerShell-Docs to request documentation for the new -Extension parameter:
MicrosoftDocs/PowerShell-Docs#12535

iSazonov · 2025-11-22T07:09:34Z

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1

+  It "should remove extension when empty string is specified" {
+    $result = Join-Path -Path "folder" -ChildPath "file.txt" -Extension ""
+    $result | Should -BeExactly "folder${SepChar}file"
+  }
+  It "should preserve dots in base name when removing extension with empty string" {
+    $result = Join-Path -Path "folder" -ChildPath "file...txt" -Extension ""
+    $result | Should -BeExactly "folder${SepChar}file.."
+  }


The tests can be in TestCases too. Below there are more.

@iSazonov Thank you for the feedback! I've consolidated six individual tests into TestCases arrays in 11ff363.

@iSazonov

- Consolidate six individual tests into TestCases arrays - Tests for removing/changing extensions are now part of parameterized tests - Created separate TestCases group for multiple child path segments - This improves consistency and maintainability Addresses review feedback from @iSazonov

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

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

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs

adityapatwardhan · 2025-12-03T22:11:47Z

The PowerShell Maintainer's discussed this PR and we have decided to not take this in v7.6. This will be part of the next v7.7 preview.

yotsuda added 2 commits November 19, 2025 09:14

Fix style issues: add blank lines before comments

6dfc96c

iSazonov reviewed Nov 19, 2025

View reviewed changes

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs Outdated Show resolved Hide resolved

iSazonov requested a review from Copilot November 19, 2025 05:55

iSazonov added the CL-General Indicates that a PR should be marked as a general cmdlet change in the Change Log label Nov 19, 2025

Copilot started reviewing on behalf of iSazonov November 19, 2025 05:56 View session

Copilot finished reviewing on behalf of iSazonov November 19, 2025 05:58

Copilot AI reviewed Nov 19, 2025

View reviewed changes

yotsuda and others added 4 commits November 19, 2025 16:38

Update src/Microsoft.PowerShell.Commands.Management/commands/manageme…

c42e238

…nt/CombinePathCommand.cs Co-authored-by: Copilot <[email protected]>

Update src/Microsoft.PowerShell.Commands.Management/commands/manageme…

afadd65

…nt/CombinePathCommand.cs Co-authored-by: Copilot <[email protected]>

Address review: use TrimEnd and add edge case tests

ca9da2a

- Use string.TrimEnd('.') instead of Substring for cleaner code - Remove redundant EndsWith check - Add tests for multiple dots, directory-like paths, and multiple child paths

Add tests for -Extension parameter with -Resolve

51fb8bc

iSazonov requested a review from Copilot November 19, 2025 11:17

Copilot started reviewing on behalf of iSazonov November 19, 2025 11:18 View session

Copilot finished reviewing on behalf of iSazonov November 19, 2025 11:21

Copilot AI reviewed Nov 19, 2025

View reviewed changes

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1 Outdated Show resolved Hide resolved

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs Outdated Show resolved Hide resolved

yotsuda and others added 2 commits November 20, 2025 12:16

Update src/Microsoft.PowerShell.Commands.Management/commands/manageme…

8822fa7

…nt/CombinePathCommand.cs Co-authored-by: Copilot <[email protected]>

Fix cross-platform test compatibility for -Extension parameter

1b02f52

Use $SepChar variable instead of hardcoded backslashes in test expectations to ensure tests pass on both Windows and Unix platforms.

iSazonov requested a review from Copilot November 20, 2025 03:38

Copilot started reviewing on behalf of iSazonov November 20, 2025 03:39 View session

Copilot finished reviewing on behalf of iSazonov November 20, 2025 03:40

Copilot AI reviewed Nov 20, 2025

View reviewed changes

test/powershell/Modules/Microsoft.PowerShell.Management/Join-Path.Tests.ps1 Show resolved Hide resolved

iSazonov requested review from SteveL-MSFT and daxian-dbw November 20, 2025 04:06

iSazonov reviewed Nov 20, 2025

View reviewed changes

brianary approved these changes Nov 20, 2025

View reviewed changes

PowerShell deleted a comment from t3xash0rnyt0ad777-commits Nov 20, 2025

kilasuit added this to Cmdlets Working Group Nov 20, 2025

kilasuit added the WG-Cmdlets-Management cmdlets in the Microsoft.PowerShell.Management module label Nov 20, 2025

iSazonov reviewed Nov 21, 2025

View reviewed changes

yotsuda and others added 3 commits November 21, 2025 23:05

Update src/Microsoft.PowerShell.Commands.Management/commands/manageme…

eda3c13

…nt/CombinePathCommand.cs Co-authored-by: Ilya <[email protected]>

Add ValidateNotNull and update XML comment for Extension parameter

b53cd39

- Add [ValidateNotNull] attribute to prevent explicit null values - Update XML comment to clarify default behavior when Extension is not specified Addresses review feedback from @iSazonov

iSazonov reviewed Nov 21, 2025

View reviewed changes

Improve test readability for Extension parameter

6096b84

- Remove Path from TestCases as it's constant across all tests - Rename ExpectedResult to ExpectedChildPath for clarity - Build full path in test body using 'folder' directly Addresses review feedback from @iSazonov

yotsuda mentioned this pull request Nov 22, 2025

Document new -Extension parameter for Join-Path cmdlet MicrosoftDocs/PowerShell-Docs#12535

Closed

2 tasks

iSazonov added the PowerShell-Docs needed The PR was reviewed and a PowerShell Docs update is needed label Nov 22, 2025

iSazonov reviewed Nov 22, 2025

View reviewed changes

yotsuda force-pushed the feature/join-path-extension branch from d6aa244 to 11ff363 Compare November 22, 2025 12:43

iSazonov requested a review from Copilot November 22, 2025 12:50

Copilot started reviewing on behalf of iSazonov November 22, 2025 12:50 View session

Copilot finished reviewing on behalf of iSazonov November 22, 2025 12:52

Copilot AI reviewed Nov 22, 2025

View reviewed changes

src/Microsoft.PowerShell.Commands.Management/commands/management/CombinePathCommand.cs Show resolved Hide resolved

iSazonov approved these changes Nov 22, 2025

View reviewed changes

iSazonov merged commit 70a6a80 into PowerShell:master Nov 22, 2025
41 of 42 checks passed

iSazonov self-assigned this Nov 22, 2025

yotsuda deleted the feature/join-path-extension branch November 22, 2025 13:52

SteveL-MSFT removed this from Cmdlets Working Group Dec 3, 2025

adityapatwardhan added the BackPort-7.6.x-Consider label Dec 3, 2025

adityapatwardhan removed the BackPort-7.6.x-Consider label Dec 3, 2025

SIRMARGIN pushed a commit to SIRMARGIN/PowerShell that referenced this pull request Dec 12, 2025

Add -Extension parameter to Join-Path cmdlet (PowerShell#26482)

1d954da

kilasuit pushed a commit to kilasuit/PowerShell that referenced this pull request Jan 2, 2026

Add -Extension parameter to Join-Path cmdlet (PowerShell#26482)

83d9a38

	ExpectedResult = "folder${SepChar}file.log"
	ExpectedChildPath = "file.log"

Add -Extension parameter to Join-Path cmdlet #26482

Add -Extension parameter to Join-Path cmdlet #26482

Uh oh!

Conversation

yotsuda commented Nov 19, 2025 • edited by iSazonov Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

PR Context

Changes

Testing

PR Checklist

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

iSazonov commented Nov 20, 2025

Uh oh!

iSazonov commented Nov 20, 2025 • edited by unfurl-links bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mklement0 Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mklement0 Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brianary left a comment

Choose a reason for hiding this comment

Uh oh!

kilasuit commented Nov 20, 2025

Uh oh!

mklement0 commented Nov 20, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yotsuda commented Nov 19, 2025 •

edited by iSazonov

Loading

iSazonov commented Nov 20, 2025 •

edited by unfurl-links bot

Loading

mklement0 Nov 20, 2025 •

edited

Loading

mklement0 Nov 20, 2025 •

edited

Loading