Format‑Path - dsccommunity/DscResource.Common GitHub Wiki

Normalizes a file system path.

Format-Path [-Path] <String> [-EnsureDriveLetterRoot] [-NoTrailingDirectorySeparator]
 [<CommonParameters>]

Normalizes a file system path to ensure proper formatting based on specified preferences. The function can add a backslash to drive letter paths and remove trailing backslashes from directory paths based on the parameters provided. It will recognize Windows drive paths and UNC paths and make sure they are formatted with backslashes, regardless of the operating system. Relative paths or absolute paths (that start with slash or backslash) will always be converted to use the system's directory separator.

When no formatting parameters are specified, the function only normalizes directory separators (using backslashes for Windows paths and the system's directory separator for other paths) while preserving any trailing separators.

Format-Path -Path 'C:/MyFolder/'

Returns 'C:\MyFolder'. Only normalizes directory separators when no formatting parameters are specified.

Format-Path -Path 'C:' -EnsureDriveLetterRoot

Returns 'C:'

Format-Path -Path 'C:\MyFolder\' -NoTrailingDirectorySeparator

Returns 'C:\MyFolder'

Format-Path -Path 'C:\MyFolder\' -EnsureDriveLetterRoot -NoTrailingDirectorySeparator

Returns 'C:\MyFolder'

Format-Path -Path 'C:' -EnsureDriveLetterRoot -NoTrailingDirectorySeparator

Returns 'C:'. The EnsureDriveLetterRoot parameter takes precedence over NoTrailingDirectorySeparator for drive letter paths.

Format-Path -Path 'MyFolder/SubFolder\'

Returns 'MyFolder\SubFolder' on Windows or 'MyFolder/SubFolder/' on Linux/macOS. Relative paths are normalized to use the system's directory separator.

Format-Path -Path '/var/log/' -NoTrailingDirectorySeparator

Returns '/var/log' on Linux/macOS or '\var\log' on Windows. Unix-style absolute paths are normalized to use the system's directory separator.

When specified, adds a trailing backslash to paths that consist of only a drive letter (e.g., 'C:' becomes 'C:'). This parameter takes precedence over NoTrailingDirectorySeparator for drive letter paths.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

When specified, removes any trailing directory separator (backslash) from paths, including drive letters.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

The file system path to normalize.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.