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:

  > 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:

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