Directory Stack

Like some other shells, Nushell provides a Directory Stack feature for easily switching between multiple directories. In Nushell, this feature is part of the Standard Library and can be accessed in several ways.

Note

In Nushell, the "stack" is represented as a list, but the overall functionality is similar to that of other shells.

dirs Module and Commands

To use the dirs command and its subcommands, first import the module using:

use std/dirs

Tips

To make the feature available whenever you start Nushell, add the above command to your startup configuration.

This makes several new commands available:

CommandDescription
dirsLists the directories on the stack
dirs addAdds one or more directories to the list. The first directory listed becomes the new active directory. Similar to the pushd command in some other shells.
dirs dropDrops the current directory from the list. The previous directory in the list becomes the new active directory. Similar to the popd command in some other shells.
dirs gotoJumps to directory by using its index in the list
dirs nextMakes the next directory on the list the active directory. If the current active directory is the last in the list, then cycle to the start of the list.
dirs prevMakes the previous directory on the list the active directory. If the current active directory is the first in the list, then cycle to the end of the list.

When we start using dirs, there is only one directory in the list, the active one. You can, as always, change this directory using the cd command.

cd ~
use std/dirs
dirs
# => ╭───┬────────┬─────────────────────────────────╮
# => │ # │ active │              path               │
# => ├───┼────────┼─────────────────────────────────┤
# => │ 0 │ true   │ /home/myuser                    │
# => ╰───┴────────┴─────────────────────────────────╯

cd ~/src/repo/nushell
dirs
# => ╭───┬────────┬─────────────────────────────────╮
# => │ # │ active │              path               │
# => ├───┼────────┼─────────────────────────────────┤
# => │ 0 │ true   │ /home/myuser/repo/nushell       │
# => ╰───┴────────┴─────────────────────────────────╯

Notice that cd only changes the Active directory.

To add the current directory to the list, change to a new active directory using the dirs add command:

dirs add ../reedline
dirs
# => ╭───┬────────┬──────────────────────────────────╮
# => │ # │ active │               path               │
# => ├───┼────────┼──────────────────────────────────┤
# => │ 0 │ false  │ /home/myuser/src/repo/nushell    │
# => │ 1 │ true   │ /home/myuser/src/repo/reedline   │
# => ╰───┴────────┴──────────────────────────────────╯

Let's go ahead and add a few more commonly used directories to the list:

dirs add ../nu_scripts
dirs add ~
dirs
# => ╭───┬────────┬────────────────────────────────────╮
# => │ # │ active │                path                │
# => ├───┼────────┼────────────────────────────────────┤
# => │ 0 │ false  │ /home/myuser/src/repo/nushell      │
# => │ 1 │ false  │ /home/myuser/src/repo/reedline     │
# => │ 2 │ false  │ /home/myuser/src/repo/nu_scripts   │
# => │ 3 │ true   │ /home/myuser                       │
# => ╰───┴────────┴────────────────────────────────────╯

We can now switch between them easily using dirs next, dirs prev or dirs goto:

dirs next
# Active was 3, is now 0
pwd
# => /home/myuser/src/repo/nushell
dirs goto 2
# => /home/myuser/src/repo/nu_scripts

When you have finished your work in a directory, you can drop it from the list using:

dirs drop
dirs
# => ╭───┬────────┬──────────────────────────────────╮
# => │ # │ active │               path               │
# => ├───┼────────┼──────────────────────────────────┤
# => │ 0 │ false  │ /home/myuser/src/repo/nushell    │
# => │ 1 │ true   │ /home/myuser/src/repo/reedline   │
# => │ 2 │ false  │ /home/myuser                     │
# => ╰───┴────────┴──────────────────────────────────╯

When we drop nu_scripts from the list, the previous directory (reedline) becomes active.

shells Aliases

Some users may prefer to think of this feature as multiple "shells within shells", where each has its own directory.

The Standard Library provides a set of aliases that can be used in place of the dirs commands above.

Import them using:

use std/dirs shells-aliases *

The built-in aliases are:

AliasDescription
shellsin place of dirs to list current "shells"/directories.
enterin place of dirs add to enter a new "shell"/dir.
dexitin place of dirs drop to exit a "shell"/dir.
gas an alias for dirs goto.
nfor dirs next
pfor dirs prev

Of course, you can also define your own aliases if desired.