# Pushd built-in

The pushd built-in pushes a directory into the directory stack.

## Syntax

- `pushd [-L|-P [-e]] [directory]`

## Description

The pushd built-in changes the working directory to directory in the same manner as the cd built-in and adds it to the directory stack. If the working directory could not be changed successfully, the stack is not modified.

## Options

The pushd built-in accepts the following option as well as the options that can be used for the cd built-in:

`--remove-duplicates`

  If the new working directory has already been in the directory stack, the existing entry is removed from the stack before the new directory is pushed into the stack.

## Operands

directory

  The pathname of the new working directory.

  If directory is a single hyphen (‘-’), the value of the `OLDPWD` variable is assumed for the new directory pathname, which is printed to the standard output.

  If directory is an integer with a plus or minus sign, it is considered as an entry index of the directory stack. The entry is removed from the stack and then pushed to the stack again.

  If directory is omitted, the working directory is changed to the directory specified by the `--default-directory=…` option. If that option is not specified either, the default is index `+1`.

## Exit status

In addition to the exit status of the cd built-in, the pushd built-in returns the following exit status:

- If the `DIRSTACK` variable is read-only, the exit status is 1.

- If the `PWD` variable is unset, the exit status is 4.

- If directory is a signed integer and the index is out of range, the exit status is 4.

- If directory is omitted, the `--default-directory=…` option is not specified, and the directory stack is empty, the exit status is 4.

## Notes

The pushd built-in is an elective built-in. It cannot be used in the POSIXly-correct mode because POSIX does not define its behavior.