Bash — The dirs Built-in

Bash has a useful feature for keeping track of multiple working directories: the directory stack.

The pushd and popd built-ins manipulate this stack, while dirs lets you display and manage it.

In this article, we'll focus on dirs and its most useful options.

The simplest form of dirs

Run:

dirs

With no arguments, Bash displays the directory stack on a single line.

For example:

$ dirs
~/projects/project-c ~/projects/project-b ~/projects/project-a ~

The first entry is the current directory, followed by the other directories stored in the stack.

For a quick overview, this is usually all you need.

Display one directory per line

When the stack contains several entries, a single line can become difficult to read.

Use -p to print each directory on its own line:

dirs -p

Example:

$ dirs -p
~/projects/project-c
~/projects/project-b
~/projects/project-a
~

This is particularly useful when directory names are long.

Display full paths

Bash normally uses abbreviated directory names where possible. For example, your home directory may appear as:

~

Use -l to display the full path:

dirs -l

Example:

$ dirs -l
/home/pavel/projects/project-c /home/pavel/projects/project-b /home/pavel/projects/project-a /home/pavel

You can combine -l with -p:

dirs -pl

Result:

/home/pavel/projects/project-c
/home/pavel/projects/project-b
/home/pavel/projects/project-a
/home/pavel

This is often the most readable format when debugging or inspecting a complicated stack.

Show stack positions

The -v option adds a position number to every entry:

dirs -v

For example:

$ dirs -v
 0  ~/projects/project-c
 1  ~/projects/project-b
 2  ~/projects/project-a
 3  ~

The current directory is position 0, followed by positions 1, 2, and so on.

You can combine this with -l:

dirs -lv

giving:

 0  /home/pavel/projects/project-c
 1  /home/pavel/projects/project-b
 2  /home/pavel/projects/project-a
 3  /home/pavel

dirs -v is particularly useful before working with a specific stack position.

Display a specific entry

dirs can display an individual entry using +N or -N.

Here, N identifies a position in the directory stack.

For example:

dirs +1

or:

dirs -1

The two forms count from different ends of the stack.

If you're unsure which entry a particular number refers to, first run:

dirs -v

For example:

 0  ~/projects/project-c
 1  ~/projects/project-b
 2  ~/projects/project-a
 3  ~

The numbered output makes the available positions much easier to understand.

Clearing the directory stack

If you want to remove the additional entries from the directory stack, use -c:

dirs -c

For example, before clearing:

$ dirs -v
 0  ~/projects/project-c
 1  ~/projects/project-b
 2  ~/projects/project-a
 3  ~

After:

$ dirs -c

the stack contains only the current directory:

$ dirs -v
 0  ~/projects/project-c

This is useful when you want to start working with a clean stack.

dirs does not change directories

One important distinction: dirs primarily reports the contents of the directory stack. It does not behave like cd.

For example:

dirs

only displays information.

Likewise:

dirs -v

doesn't move you anywhere.

The commands responsible for manipulating the stack and changing directories are pushd and popd.

A useful way to remember the relationship is:

pushd  → manipulate the directory stack and change directory
popd   → remove an entry and change directory
dirs   → inspect the directory stack

We'll look at pushd and popd separately.

A practical example

Suppose the directory stack currently looks like this:

dirs -v

 0  ~/projects/frontend
 1  ~/projects/backend
 2  ~/projects/infrastructure
 3  ~/documents

Different forms of dirs let you inspect the same stack in different ways.

Normal output:

dirs

~/projects/frontend ~/projects/backend ~/projects/infrastructure ~/documents

One entry per line:

dirs -p

~/projects/frontend
~/projects/backend
~/projects/infrastructure
~/documents

Full paths:

dirs -l

/home/pavel/projects/frontend /home/pavel/projects/backend /home/pavel/projects/infrastructure /home/pavel/documents

Numbered entries:

dirs -v

 0  ~/projects/frontend
 1  ~/projects/backend
 2  ~/projects/infrastructure
 3  ~/documents

The data is the same; only the presentation changes.

The directory stack is not command history

It is easy to confuse the directory stack with Bash's command history.

Your command history might contain:

cd ~/projects
cd ~/documents
ls
cd ~/projects/backend

The directory stack is different. It contains directories managed through Bash's directory-stack mechanism.

So dirs does not mean:

"Show me every directory I have visited."

It means:

"Show me the directories currently stored in the directory stack."

This distinction becomes important when working with cd, pushd, and popd.

Useful dirs options

The most important forms are:

Useful combinations include:

dirs -pl
dirs -lv

For example, dirs -lv gives you full paths together with their positions, which is handy when investigating a complicated stack.

dirs is a Bash built-in

dirs is not normally an external executable. It is part of Bash itself.

You can verify this with:

type dirs

Bash should report:

dirs is a shell builtin

You can also ask Bash for its built-in documentation:

help dirs

This is a useful habit when working with Bash built-ins: Bash can often tell you directly how its own commands work.

Conclusion

The dirs built-in provides a simple interface for inspecting Bash's directory stack.

The commands worth remembering are:

dirs
dirs -p
dirs -l
dirs -v
dirs -c

When you need to inspect a particular position:

dirs +N
dirs -N

The basic idea is straightforward:

pushd  → work with the directory stack
popd   → remove entries from the stack
dirs   → inspect the stack

On its own, dirs mostly prints information. Its real usefulness becomes apparent when combined with pushd and popd, which turn the directory stack into a convenient way to move between several working locations without repeatedly typing long paths.

For now, dirs has shown us what's in the box. Next, we'll see how to start putting things into it and taking them out.