Export (0) Print
Expand All

Push-Location

Updated: May 8, 2014

Applies To: Windows PowerShell 4.0

Push-Location

Adds the current location to the top of a location stack.

Aliases

The following abbreviations are aliases for this cmdlet:

  • pushd

Syntax

Parameter Set: Path
Push-Location [[-Path] <String> ] [-PassThru] [-StackName <String> ] [-UseTransaction] [ <CommonParameters>]

Parameter Set: LiteralPath
Push-Location [-LiteralPath <String> ] [-PassThru] [-StackName <String> ] [-UseTransaction] [ <CommonParameters>]




Detailed 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.

Parameters

-LiteralPath<String>

Specifies the path to the new location. Unlike the Path parameter, the value of the LiteralPath parameter is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.


Aliases

none

Required?

false

Position?

named

Default Value

none

Accept Pipeline Input?

true (ByValue, ByPropertyName)

Accept Wildcard Characters?

false

-PassThru

Passes an object representing the location to the pipeline. By default, this cmdlet does not generate any output.


Aliases

none

Required?

false

Position?

named

Default Value

False

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-Path<String>

Changes your location to the location specified by this path after it adds (pushes) the current location onto the top of the stack. Enter a path to any location whose provider supports this cmdlet. Wildcards are permitted. The parameter name ("Path") is optional.


Aliases

none

Required?

false

Position?

1

Default Value

none

Accept Pipeline Input?

true (ByValue, ByPropertyName)

Accept Wildcard Characters?

true

-StackName<String>

Specifies the location stack to which the current location is added. Enter a location stack name. If the stack does not exist, Push-Location creates it.

Without this parameter, Push-Location adds the location to the current location stack. By default, the current location stack is the unnamed default location stack that Windows PowerShell creates. To make a location stack the current location stack, use the StackName parameter of the Set-Location cmdlet. For more information about location stacks, see the Notes.

NOTE: Push-Location cannot add a location to the unnamed default stack unless it is the current location stack.


Aliases

none

Required?

false

Position?

named

Default Value

Default stack

Accept Pipeline Input?

true (ByPropertyName)

Accept Wildcard Characters?

false

-UseTransaction

Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_Transactions


Required?

false

Position?

named

Default Value

false

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.String

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


Outputs

The output type is the type of the objects that the cmdlet emits.

  • 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

  • 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. Windows PowerShell lets you store provider locations in location stacks.

    Windows PowerShell creates an unnamed default location stack and you can create multiple named location stacks. If you do not specify a stack name, Windows 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 Windows 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 cannot no longer use Push-Location or Pop-Location cmdlets add or get items from the default stack or use Get-Location command 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.

Examples

-------------------------- EXAMPLE 1 --------------------------

This command 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 command pushes the current location onto the RegFunction stack and changes the current location to the HKLM:\Software\Policies location. You can use the Location cmdlets in any Windows PowerShell drive (PSDrive).


PS C:\> push-location HKLM:\Software\Policies -stackname RegFunction

-------------------------- EXAMPLE 3 --------------------------

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


PS C:\> push-location

-------------------------- EXAMPLE 4 --------------------------

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

The first command pushes the current location onto a new stack named Stack2, and then changes the current location to the home directory (%USERPROFILE%), which is represented in the command by the tilde symbol (~) or $home. 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 (PS 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.


PS C:\> push-location ~ -stackname Stack2
PS C:\Users\User01> pop-location -stackname Stack2
PS C:\>

Related topics



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft