Push-Location

Syntax

Push-Location
    [[-Path] <String>]
    [-PassThru]
    [-StackName <String>]
    [<CommonParameters>]

Push-Location
    [-LiteralPath <String>]
    [-PassThru]
    [-StackName <String>]
    [<CommonParameters>]

Description

The Push-Location cmdlet adds ("pushes") the current location onto a location stack. If you specify a path, Push-Location pushes the current location onto a location stack and then changes the current location to the location specified by the path. You can use the Pop-Location cmdlet to get locations from the location stack.

By default, the Push-Location cmdlet pushes the current location onto the current location stack, but you can use the StackName parameter to specify an alternate location stack. If the stack does not exist, Push-Location creates it.

For more information about location stacks, see the Notes.

Examples

Example 1

This example pushes the current location onto the default location stack and then changes the location to C:\Windows.

PS C:\> Push-Location C:\Windows

Example 2

This example pushes the current location onto the RegFunction stack and changes the current location to the HKLM:\Software\Policies location.

PS C:\> Push-Location HKLM:\Software\Policies -StackName RegFunction

You can use the Location cmdlets in any PowerShell drive (PSDrive).

Example 3

This command pushes the current location onto the default stack. It does not change the location.

PS C:\> Push-Location

Example 4 - Create and use a named stack

These commands show how to create and use a named location stack.

PS C:\> Push-Location ~ -StackName Stack2
PS C:\Users\User01> Pop-Location -StackName Stack2
PS C:\>

The first command pushes the current location onto a new stack named Stack2, and then changes the current location to the home directory, represented in the command by the tilde symbol (~), which when used on a FileSystem provider drives is equivalent to $HOME and $env:USERPROFILE.

If Stack2 does not already exist in the session, Push-Location creates it. The second command uses the Pop-Location cmdlet to pop the original location (C:\) from the Stack2 stack. Without the StackName parameter, Pop-Location would pop the location from the unnamed default stack.

For more information about location stacks, see the Notes.

Parameters

-LiteralPath

-PassThru

-Path

-StackName

Inputs

String

You can pipe a string that contains a path (but not a literal path) to Push-Location.

Outputs

None or System.Management.Automation.PathInfo

When you use the PassThru parameter, Push-Location generates a System.Management.Automation.PathInfo object that represents the location. Otherwise, this cmdlet does not generate any output.

Notes

PowerShell supports multiple runspaces per process. Each runspace has its own current directory. This is not the same as [System.Environment]::CurrentDirectory. This behavior can be an issue when calling .NET APIs or running native applications without providing explicit directory paths.

Even if the location cmdlets did set the process-wide current directory, you can't depend on it because another runspace might change it at any time. You should use the location cmdlets to perform path-based operations using the current working directory specific to the current runspace.

A stack is a last-in, first-out list in which only the most recently added item is accessible. You add items to a stack in the order that you use them, and then retrieve them for use in the reverse order. PowerShell lets you store provider locations in location stacks.

PowerShell creates an unnamed default location stack and you can create multiple named location stacks. If you do not specify a stack name, PowerShell uses the current location stack. By default, the unnamed default location is the current location stack, but you can use the Set-Location cmdlet to change the current location stack.

To manage location stacks, use the PowerShell Location cmdlets, as follows.

• To add a location to a location stack, use the Push-Location cmdlet.

• To get a location from a location stack, use the Pop-Location cmdlet.

• To display the locations in the current location stack, use the Stack parameter of the Get-Location cmdlet.

• To display the locations in a named location stack, use the StackName parameter of the Get-Location cmdlet.

• To create a new location stack, use the StackName parameter of the Push-Location cmdlet. If you specify a stack that does not exist, Push-Location creates the stack.

• To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet.

The unnamed default location stack is fully accessible only when it is the current location stack. If you make a named location stack the current location stack, you can no longer use the Push-Location or Pop-Location cmdlets to add or get items from the default stack or use the Get-Location cmdlet to display the locations in the unnamed stack. To make the unnamed stack the current stack, use the StackName parameter of the Set-Location cmdlet with a value of $null or an empty string ("").

You can also refer to Push-Location by its built-in alias, pushd. For more information, see about_Aliases.

The Push-Location cmdlet is designed to work with the data exposed by any provider. To list the providers available in your session, type Get-PSProvider. For more information, see about_Providers.

Related Links

• Get-Location
• Pop-Location
• Set-Location
• about_Aliases
• about_Providers