diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts index bb77a82c10b..0d8ea1685bd 100644 --- a/.vuepress/configs/sidebar/en.ts +++ b/.vuepress/configs/sidebar/en.ts @@ -76,7 +76,7 @@ export const sidebarEn: SidebarConfig = { '/book/stdout_stderr_exit_codes.md', '/book/escaping.md', '/book/3rdpartyprompts.md', - '/book/shells_in_shells.md', + '/book/directory_stack.md', '/book/line_editor.md', '/book/custom_completions.md', '/book/externs.md', diff --git a/book/directory_stack.md b/book/directory_stack.md new file mode 100644 index 00000000000..fb43195d29a --- /dev/null +++ b/book/directory_stack.md @@ -0,0 +1,137 @@ +# 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](./standard_library.md) 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. +::: + +[[toc]] + +## `dirs` Module and Commands + +To use the `dirs` command and its subcommands, first import the module using: + +```nu +use std/dirs +``` + +::: tip +To make the feature available whenever you start Nushell, add the above command to your [startup configuration](./configuration.md). +::: + +This makes several new commands available: + +| Command | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dirs` | Lists the directories on the stack | +| `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. | +| `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. | +| `dirs goto` | Jumps to directory by using its index in the list | +| `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. | +| `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. | + +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. + +```nu +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: + +```nu +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: + +```nu +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`: + +```nu +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: + +```nu +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: + +```nu +use std/dirs shell-aliases * +``` + +The built-in aliases are: + +| Alias | Description | +| -------- | -------------------------------------------------------- | +| `shells` | in place of `dirs` to list current "shells"/directories. | +| `enter` | in place of `dirs add` to enter a new "shell"/dir. | +| `dexit` | in place of `dirs drop` to exit a "shell"/dir. | +| `g` | as an alias for `dirs goto`. | +| `n` | for `dirs next` | +| `p` | for `dirs prev` | + +Of course, you can also define your own aliases if desired. diff --git a/book/nu_as_a_shell.md b/book/nu_as_a_shell.md index 08a7b3a8f69..3109b11b705 100644 --- a/book/nu_as_a_shell.md +++ b/book/nu_as_a_shell.md @@ -14,7 +14,7 @@ This brings in some additional design considerations so please refer to the link The other sections explain how to work with [stdout, stderr and exit codes](stdout_stderr_exit_codes.md), how to [escape a command call to the external command call](escaping.md), and how to [configure 3rd party prompts](3rdpartyprompts.md) to work with Nushell. -An interesting feature of Nushell is [shells](shells_in_shells.md) which let you work in multiple directories simultaneously. +An interesting feature of Nushell is the [Directory Stack](directory_stack.md) which let you work in multiple directories simultaneously. Nushell also has its own line editor [Reedline](line_editor.md). With Nushell's config, it is possible to configure some of the Reedline's features, such as the prompt, keybindings, history, or menus. diff --git a/book/shells_in_shells.md b/book/shells_in_shells.md deleted file mode 100644 index d9fd92ad1a8..00000000000 --- a/book/shells_in_shells.md +++ /dev/null @@ -1,52 +0,0 @@ -# Shells in Shells - -## Working in Multiple Directories - -While it's common to work in one directory, it can be handy to work in multiple places at the same time. For this, Nu offers the concept of "shells". As the name implies, they're a way of running multiple shells in one, allowing you to quickly jump between working directories and more. - -To get started, let's enter a directory: - -```nu -/home/sophia/Source/nushell(main)> enter ../book -/home/sophia/Source/book(main)> ls -────┬────────────────────┬──────┬────────┬───────────── - # │ name │ type │ size │ modified -────┼────────────────────┼──────┼────────┼───────────── - 0 │ 404.html │ File │ 429 B │ 2 hours ago - 1 │ CONTRIBUTING.md │ File │ 955 B │ 2 hours ago - 2 │ Gemfile │ File │ 1.1 KB │ 2 hours ago - 3 │ Gemfile.lock │ File │ 6.9 KB │ 2 hours ago -``` - -Entering is similar to changing directories (as we saw with the [`cd`](/commands/docs/cd.md) command). This allows you to jump into a directory to work in it. Instead of changing the directory, we now are in two directories. To see this more clearly, we can use the [`shells`](/commands/docs/shells.md) command to list the current directories we have active: - -```nu -/home/sophia/Source/book(main)> enter ../music -/home/sophia/Source/music(main)> shells -───┬────────┬───────────────────────────── - # │ active │ path -───┼────────┼───────────────────────────── - 0 │ false │ /home/sophia/Source/nushell - 1 │ false │ /home/sophia/Source/book - 2 │ true │ /home/sophia/Source/music -───┴────────┴───────────────────────────── -``` - -The [`shells`](/commands/docs/shells.md) command shows us there are three shells: our original "nushell" source directory, "book" directory and "music" directory which is currently active. - -We can jump between these shells with the [`n`](/commands/docs/n.md), [`p`](/commands/docs/p.md) and [`g`](/commands/docs/g.md) shortcuts, short for "next", "previous" and "goto": - -```nu -/home/sophia/Source/music(main)> p -/home/sophia/Source/book(main)> n -/home/sophia/Source/music(main)> g 0 -/home/sophia/Source/nushell(main)> -``` - -We can see the directory changing, but we're always able to get back to a previous directory we were working on. This allows us to work in multiple directories in the same session. - -## Exiting the Shell - -You can leave a shell you have [`enter`](/commands/docs/enter.md)ed using the `dexit` command. - -You can always quit Nu, even if multiple shells are active, using `exit`. diff --git a/book/table_of_contents.md b/book/table_of_contents.md index ceccd782ca0..c985eb2d3d8 100644 --- a/book/table_of_contents.md +++ b/book/table_of_contents.md @@ -24,7 +24,7 @@ - [Scripts](scripts.md) - Creating your own scripts - [Metadata](metadata.md) - An explanation of Nu's metadata system - [Creating your own errors](creating_errors.md) - Creating your own error messages -- [Shells](shells_in_shells.md) - Working with multiple locations +- [Directory Stack](directory_stack.md) - Working with multiple locations - [Escaping commands](escaping.md) - Escaping to native commands of the same name - [Plugins](plugins.md) - Enhancing Nushell with more features using plugins - [Parallelism](parallelism.md) - Running your code in parallel diff --git a/de/book/nu_as_a_shell.md b/de/book/nu_as_a_shell.md index 51ac869298c..8357c8c3c13 100644 --- a/de/book/nu_as_a_shell.md +++ b/de/book/nu_as_a_shell.md @@ -16,7 +16,7 @@ Dies bringt einige zusätzliche Design Überlegungen mit sich, welche in den ver Die anderen Kapitel erklären wie mit [stdout, stderr und exit codes (EN)](/book/stdout_stderr_exit_codes.md) gearbeitet werden kann, oder wie ein [Befehl zu einem externer Befehl "escaped"](escaping.md) werden kann. Sowie wie ein [Drittanbieter Prompt](3rdpartyprompts.md) zur Zusammenarbeit mit Nushell bewegt werden kann. -Ein interessantes Merkmal von Nushell ist [Shell in Shells (EN)](/book/shells_in_shells.md) welches erlaubt in mehreren Verzeichnissen gleichzeitig zu arbeiten. +Ein interessantes Merkmal von Nushell ist [Shell in Shells (EN)](/book/directory_stack.md) welches erlaubt in mehreren Verzeichnissen gleichzeitig zu arbeiten. Nushell hat auch seinen eigenen Zeilen Editor [Reedline (EN)](/book/line_editor.md). In Nushells Konfiguration ist es möglich einige Merkmale von Reedline wie Prompt, Tastenkombinationen, History oder Menus einzustellen. @@ -25,6 +25,6 @@ Es ist auch möglich, eigene [Signaturen für externe Befehle (EN)](/book/extern [Farben und Themen in Nu](coloring_and_theming.md)) geht ins Detail zum Thema, wie Nushells Aussehen konfiguriert werden kann. -Sind einige Befehle geplant , die im Hintergrund ablaufen sollen, so kann darüber in [Hintergrund Tasks in Nu](background_task.md) nachgelesen werden. +Sind einige Befehle geplant , die im Hintergrund ablaufen sollen, so kann darüber in [Hintergrund Tasks in Nu](background_task.md) nachgelesen werden. Schliesslich erklärt [Hooks](hooks.md) wie Fragmente von Nushell Code beim Auftreten gewisser Ereignisse ausgeführt werden kann. diff --git a/zh-CN/book/shells_in_shells.md b/zh-CN/book/shells_in_shells.md index 1527e44944b..04fe815c772 100644 --- a/zh-CN/book/shells_in_shells.md +++ b/zh-CN/book/shells_in_shells.md @@ -18,7 +18,7 @@ 3 │ Gemfile.lock │ File │ 6.9 KB │ 2 hours ago ``` -进入(`enter`)类似于改变目录（正如我们在`cd`命令中看到的那样）。这允许你跳入一个目录，在其中工作。我们现在是在两个目录中，而不是改变目录。为了更清楚地看到这一点，我们可以使用[`shells`](/commands/docs/shells.md)命令来列出我们当前的活动目录： +进入(`enter`)类似于改变目录（正如我们在`cd`命令中看到的那样）。这允许你跳入一个目录，在其中工作。我们现在是在两个目录中，而不是改变目录。为了更清楚地看到这一点，我们可以使用`shells`命令来列出我们当前的活动目录： ```nu /home/sophia/Source/book(main)> shells @@ -32,7 +32,7 @@ ``` -[`shells`](/commands/docs/shells.md)命令显示目前有三个 Shells 处于活动状态：我们最初的 "nushell" 源目录和现在的新 "book" 目录。 +`shells`命令显示目前有三个 Shells 处于活动状态：我们最初的 "nushell" 源目录和现在的新 "book" 目录。 我们可以用 `n`, `p` 和 `g` 的快捷命令在这些 Shell 之间跳转，这是 "next"、"previous" 和 "go" 的缩写：