# Dirs built-in

The dirs built-in prints the contents of the directory stack.

## Syntax

- `dirs [-cv] [index..]`

## Description

The directory stack is a feature that records history of working directories. You can use the pushd built-in to save a working directory in the directory stack, the popd built-in to recall the saved working directory, and the dirs built-in to see the stack contents. Those built-ins use the `DIRSTACK` array and the `PWD` variable to save the stack contents. Modifying the array means modifying the stack contents.

Directory stack entries are indexed by signed integers. The entry of index +0 is the current working directory, +1 is the last saved directory, +2 is the second last, and so on. Negative indices are in the reverse order: the entry of index -0 is the first saved directory, -1 is the second, and -n is the current working directory if the stack has n entries,

When executed without the `-c` (`--clear`) option, the dirs built-in prints the current contents of the directory stack to the standard output. With the `-c` (`--clear`) option, the built-in clears the directory stack.

## Options

`-c`
`--clear`

  Clear the directory stack contents except for the current working directory, which has index +0.

`-v`
`--verbose`

  Print indices when printing stack contents.

## Operands

index

  The index of a stack entry to be printed.

  You can specify more than one index. If you do not specify any index, all the entries are printed.

## Exit status

The exit status of the dirs built-in is zero unless there is any error.

## Notes

The dirs built-in is a semi-special built-in. In the POSIX standard, it is defined as a command with unspecified behavior.