ConvertTo‑RelativePath

SYNOPSIS

Converts an absolute path to a relative path.

SYNTAX

ConvertTo-RelativePath [-AbsolutePath] <String> [[-CurrentLocation] <String>] [-DirectorySeparator <Char>]
 [<CommonParameters>]

DESCRIPTION

The ConvertTo-RelativePath command takes an absolute path and converts it to a relative path based on the current location. The function performs platform-aware path validation to ensure that both the absolute path and current location are valid for the current operating system before attempting path conversion.

If the absolute path starts with the current location (after normalization), the function creates a relative path. Otherwise, it returns the original absolute path unchanged.

The function handles mixed directory separators and uses .NET Path methods for cross-platform compatibility, with additional validation to prevent unexpected behavior when processing platform-incompatible paths.

EXAMPLES

EXAMPLE 1

ConvertTo-RelativePath -AbsolutePath '/source/Viscalyx.Common/source/Public/ConvertTo-RelativePath.ps1' -CurrentLocation "/source/Viscalyx.Common"

Returns "./source/Public/ConvertTo-RelativePath.ps1", which is the relative path of the given absolute path based on the current location.

EXAMPLE 2

ConvertTo-RelativePath -AbsolutePath 'C:\Projects\MyApp\src\file.txt' -CurrentLocation 'C:\Projects\MyApp'

Returns a relative path (".\src\file.txt" on Windows, "./src/file.txt" on Unix-like systems). Use -DirectorySeparator to override the separator if needed.

EXAMPLE 3

ConvertTo-RelativePath -AbsolutePath 'C:\Projects\MyApp\src\file.txt' -CurrentLocation 'C:\Projects\MyApp' -DirectorySeparator '/'

Returns "./src/file.txt" using forward slash as the directory separator, even on Windows platforms.

PARAMETERS

-AbsolutePath

Specifies the absolute path that needs to be converted to a relative path.

Type: String
Parameter Sets: (All)
Aliases:

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

-CurrentLocation

Specifies the current location used as a reference for converting the absolute path to a relative path. If not specified, the function uses the current location obtained from Get-Location.

Type: String
Parameter Sets: (All)
Aliases:

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

-DirectorySeparator

Specifies the directory separator character to use when normalizing paths and constructing the relative path. If not specified, the function uses the current platform's directory separator character.

Type: Char
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: [System.IO.Path]::DirectorySeparatorChar
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

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

INPUTS

System.String

Absolute path to convert to a relative path.

OUTPUTS

System.String

The relative path based on the current location.

NOTES

This function uses .NET Path methods for cross-platform compatibility with additional platform-aware validation. The function performs the following checks:

Validates that both paths are considered absolute/rooted for the current platform 2. Uses GetFullPath() for normalization only when paths are platform-compatible 3. Includes error handling for cases where path operations might fail 4. Returns the original absolute path unchanged if conversion is not applicable

Cross-platform behavior:

• Windows paths (C:\path) work correctly on Windows but are returned unchanged on Unix-like systems
• Unix paths (/path) work correctly on Unix-like systems but may have limitations on Windows
• Mixed directory separators are normalized when possible

RELATED LINKS