The Directory Stack

Zsh has an internal directory stack. This is a facility that can help you manage working in many different direcotries throughout your zsh login session.

Working with the Stack

Directories get placed onto the directory stack with the pushd command. Directories get removed from the stack with popd. The stack can be viewed or rebuilt with the dirs command.

`dirs`

To view the contents of the stack, simply enter the dirs -v command. (dirs with no arguments will work, but the output can get obnoxious and unreadable).

> dirs -v
0       /etc/mail
1       /var
2       /tmp
3       /usr/local
4       /usr
5       ~
>

If you would like to rebuild the stack from scratch, use dirs followed by a list of directory names. Zsh then:

removes all entries from stack
places all arguments on the stack, starting with the rightmost argument
pushes $PWD onto the top of the stack

> echo $PWD
/tmp
> dirs /usr/local/ews /usr/local /usr /var /var/log $HOME
> dirs -v
0       /tmp
1       /usr/local/ews
2       /usr/local
3       /usr
4       /var
5       /var/log
6       ~
>

`popd`

popd removes entries from the directory stack and cd's to the new top directory.

Behavior:

popd, with no arguments, removes the current top directory entry from the stack, and cd's to the new top directory.
popd can take an argument, + or - n, where n is an integer.
- If the argument is +n, popd removes the nth stack element from the top
- If the argument is -n, popd removes the nth stack entry from the right bottom.
Counting starts at zero.
If you turn on the shell option PUSHD_MINUS, the meaning of + and - are reversed for pushd and popd.)

> dirs -v
0       /tmp
1       /usr/local/ews
2       /usr/local
3       /usr
4       /var
5       /var/log
6       ~
> setopt PUSHD_MINUS
> popd -2
> echo $PWD
/tmp
> dirs -v
0       /tmp
1       /usr/local/ews
2       /usr
3       /var
4       /var/log
5       ~
> popd
> echo $PWD
/usr/local/ews
> dirs -v
0       /usr/local/ews
1       /usr
2       /var
3       /var/log
4       ~
>

`pushd`

pushs changes the current directory to an argument you specify, and places $OLDPWD on the top of the stack.

1st form: pushd [arg]

Changes current directory to arg. If arg is not given, change to the second stack entry. (1 , 2)

> pwd
/etc
> dirs -v
0       /etc
1       /usr/local/ews
> pushd mail
> dirs -v
0       /etc/mail
1       /etc
2       /usr/local/ews

2nd form: pushd old new

pushd substitues the strings new for the string old, and tries to change to this new directory. (Similar to the second form of cd).

3rd form: pushd {+|-}n

Causes pushd to change the current directory by rotating the directory stack. The argument n is described in the popd section on this page.

> setopt PUSHD_MINUS
> dirs -v
0       /etc/mail
1       /usr/local
2       /usr
3       ~
> pushd -2
/usr
> dirs -v
0       /usr
1       ~
2       /etc/mail
3       /usr/local

Filename Expansion and the Directory Stack

Zsh offers a nice way to reference the directory stack quickly in your daily work. The description below is taken directly from the man page:

     A `~' followed by a number is replaced by the  directory  at
     that position in the directory stack.  `~0' is equivalent to
     `~+', and `~1' is the top of the stack.  `~+' followed by  a
     number  is replaced by the directory at that position in the
     directory stack.  `~+0' is equivalent to `~+', and `~+1'  is
     the top of the stack.  `~-' followed by a number is replaced
     by the directory that many positions from the bottom of  the
     stack.   `~-0'  is the bottom of the stack.  The PUSHD_MINUS
     option exchanges the effects of `~+' and `~-' where they are
     followed by a number.