|
| 1 | +# Directory Stack |
| 2 | + |
| 3 | +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](./standard_library.md) and can be accessed in several ways. |
| 4 | + |
| 5 | +::: note |
| 6 | +In Nushell, the "stack" is represented as a `list`, but the overall functionality is similar to that of other shells. |
| 7 | +::: |
| 8 | + |
| 9 | +[[toc]] |
| 10 | + |
| 11 | +## `dirs` Module and Commands |
| 12 | + |
| 13 | +To use the `dirs` command and its subcommands, first import the module using: |
| 14 | + |
| 15 | +```nu |
| 16 | +use std/dirs |
| 17 | +``` |
| 18 | + |
| 19 | +::: tip |
| 20 | +To make the feature available whenever you start Nushell, add the above command to your [startup configuration](./configuration.md). |
| 21 | +::: |
| 22 | + |
| 23 | +This makes several new commands available: |
| 24 | + |
| 25 | +| Command | Description | |
| 26 | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 27 | +| `dirs` | Lists the directories on the stack | |
| 28 | +| `dirs add` | Adds 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. | |
| 29 | +| `dirs drop` | Drops 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. | |
| 30 | +| `dirs goto` | Jumps to directory by using its index in the list | |
| 31 | +| `dirs next` | Makes 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. | |
| 32 | +| `dirs prev` | Makes 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. | |
| 33 | + |
| 34 | +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. |
| 35 | + |
| 36 | +```nu |
| 37 | +cd ~ |
| 38 | +use std/dirs |
| 39 | +dirs |
| 40 | +# => ╭───┬────────┬─────────────────────────────────╮ |
| 41 | +# => │ # │ active │ path │ |
| 42 | +# => ├───┼────────┼─────────────────────────────────┤ |
| 43 | +# => │ 0 │ true │ /home/myuser │ |
| 44 | +# => ╰───┴────────┴─────────────────────────────────╯ |
| 45 | +
|
| 46 | +cd ~/src/repo/nushell |
| 47 | +dirs |
| 48 | +# => ╭───┬────────┬─────────────────────────────────╮ |
| 49 | +# => │ # │ active │ path │ |
| 50 | +# => ├───┼────────┼─────────────────────────────────┤ |
| 51 | +# => │ 0 │ true │ /home/myuser/repo/nushell │ |
| 52 | +# => ╰───┴────────┴─────────────────────────────────╯ |
| 53 | +
|
| 54 | +``` |
| 55 | + |
| 56 | +Notice that `cd` only changes the Active directory. |
| 57 | + |
| 58 | +To _add_ the current directory to the list, change to a new active directory using the `dirs add` command: |
| 59 | + |
| 60 | +```nu |
| 61 | +dirs add ../reedline |
| 62 | +dirs |
| 63 | +# => ╭───┬────────┬──────────────────────────────────╮ |
| 64 | +# => │ # │ active │ path │ |
| 65 | +# => ├───┼────────┼──────────────────────────────────┤ |
| 66 | +# => │ 0 │ false │ /home/myuser/src/repo/nushell │ |
| 67 | +# => │ 1 │ true │ /home/myuser/src/repo/reedline │ |
| 68 | +# => ╰───┴────────┴──────────────────────────────────╯ |
| 69 | +``` |
| 70 | + |
| 71 | +Let's go ahead and add a few more commonly used directories to the list: |
| 72 | + |
| 73 | +```nu |
| 74 | +dirs add ../nu_scripts |
| 75 | +dirs add ~ |
| 76 | +dirs |
| 77 | +# => ╭───┬────────┬────────────────────────────────────╮ |
| 78 | +# => │ # │ active │ path │ |
| 79 | +# => ├───┼────────┼────────────────────────────────────┤ |
| 80 | +# => │ 0 │ false │ /home/myuser/src/repo/nushell │ |
| 81 | +# => │ 1 │ false │ /home/myuser/src/repo/reedline │ |
| 82 | +# => │ 2 │ false │ /home/myuser/src/repo/nu_scripts │ |
| 83 | +# => │ 3 │ true │ /home/myuser │ |
| 84 | +# => ╰───┴────────┴────────────────────────────────────╯ |
| 85 | +``` |
| 86 | + |
| 87 | +We can now switch between them easily using `dirs next`, `dirs prev` or `dirs goto`: |
| 88 | + |
| 89 | +```nu |
| 90 | +dirs next |
| 91 | +# Active was 3, is now 0 |
| 92 | +pwd |
| 93 | +# => /home/myuser/src/repo/nushell |
| 94 | +dirs goto 2 |
| 95 | +# => /home/myuser/src/repo/nu_scripts |
| 96 | +``` |
| 97 | + |
| 98 | +When you have finished your work in a directory, you can drop it from the list using: |
| 99 | + |
| 100 | +```nu |
| 101 | +dirs drop |
| 102 | +dirs |
| 103 | +# => ╭───┬────────┬──────────────────────────────────╮ |
| 104 | +# => │ # │ active │ path │ |
| 105 | +# => ├───┼────────┼──────────────────────────────────┤ |
| 106 | +# => │ 0 │ false │ /home/myuser/src/repo/nushell │ |
| 107 | +# => │ 1 │ true │ /home/myuser/src/repo/reedline │ |
| 108 | +# => │ 2 │ false │ /home/myuser │ |
| 109 | +# => ╰───┴────────┴──────────────────────────────────╯ |
| 110 | +``` |
| 111 | + |
| 112 | +When we drop `nu_scripts` from the list, the previous directory (`reedline`) becomes active. |
| 113 | + |
| 114 | +## `shells` Aliases |
| 115 | + |
| 116 | +Some users may prefer to think of this feature as multiple "shells within shells", where each has its own directory. |
| 117 | + |
| 118 | +The Standard Library provides a set of aliases that can be used in place of the `dirs` commands above. |
| 119 | + |
| 120 | +Import them using: |
| 121 | + |
| 122 | +```nu |
| 123 | +use std/dirs shell-aliases * |
| 124 | +``` |
| 125 | + |
| 126 | +The built-in aliases are: |
| 127 | + |
| 128 | +| Alias | Description | |
| 129 | +| -------- | -------------------------------------------------------- | |
| 130 | +| `shells` | in place of `dirs` to list current "shells"/directories. | |
| 131 | +| `enter` | in place of `dirs add` to enter a new "shell"/dir. | |
| 132 | +| `dexit` | in place of `dirs drop` to exit a "shell"/dir. | |
| 133 | +| `g` | as an alias for `dirs goto`. | |
| 134 | +| `n` | for `dirs next` | |
| 135 | +| `p` | for `dirs prev` | |
| 136 | + |
| 137 | +Of course, you can also define your own aliases if desired. |
0 commit comments