Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
5af385b
Fix doc statements that contradict Nushell 0.117.0
fdncred Nov 14, 2026
2fbe7a3
Document type, string, and operator features that had no docs
fdncred Nov 14, 2026
d6cf32c
Document environment and startup features that had no docs
fdncred Nov 14, 2026
3414a2e
Document tooling and plugin features that had no docs
fdncred Nov 14, 2026
d1073ad
Document definition and control flow features that had no docs
fdncred Nov 14, 2026
3af40c0
Document line editor and standard library features that had no docs
fdncred Nov 14, 2026
83d4b15
Fill gaps in the custom command, variable, and alias docs
fdncred Nov 14, 2026
1b59069
Fill gaps in the data type docs
fdncred Nov 14, 2026
4e2acb8
Add a configuration reference and fill gaps in the config docs
fdncred Nov 14, 2026
6323434
Fill gaps in the operator and shell migration docs
fdncred Nov 14, 2026
462c651
Fill gaps in the environment and special variable docs
fdncred Nov 14, 2026
3fedd9d
Fill gaps in the plugin user and author docs
fdncred Nov 14, 2026
5dee96a
Fill gaps in the pipeline, output, and external command docs
fdncred Nov 14, 2026
45d84a8
Fill gaps in the theming and hooks docs
fdncred Nov 14, 2026
b6616fc
Add a std-rfc reference page
fdncred Nov 14, 2026
59322a1
Fill gaps in the custom completion docs
fdncred Nov 14, 2026
af789e1
Fill gaps in the string, regex, and structured data docs
fdncred Nov 14, 2026
79160e7
Fill gaps in the dataframes chapter
fdncred Nov 14, 2026
9ca5181
Fill gaps in the filter command docs
fdncred Nov 14, 2026
d787cc5
Fill gaps in the metadata, debugging, and editor tooling docs
fdncred Nov 14, 2026
3e9e934
Fill gaps in the explore, tui, MCP, and background job docs
fdncred Nov 14, 2026
feebfbe
Add standard library module pages and fill gaps in the std docs
fdncred Nov 14, 2026
a487b9d
Fill gaps in the data, filesystem, and network docs
fdncred Nov 14, 2026
f6cf80a
Fill gaps in the module, overlay, script, and control flow docs
fdncred Nov 14, 2026
7b51941
Fill gaps in the line editor docs
fdncred Nov 14, 2026
a7ef4d9
Add a binary data page and document the bytes, bits, and hash commands
fdncred Nov 14, 2026
70c7cda
Add a numbers page and document the math, random, and date commands
fdncred Nov 14, 2026
abe873b
Add paths and terminal pages and document the system commands
fdncred Nov 14, 2026
60b295e
Add a matrices chapter and document more filter commands
fdncred Nov 14, 2026
6f34683
Document string case, comparison, and conversion commands
fdncred Nov 14, 2026
283ff0c
Document the core plugins' commands
fdncred Nov 14, 2026
6f1a157
Add Polars command pages to the dataframes chapter
fdncred Nov 14, 2026
605acbe
Add a data formats page and document the format commands
fdncred Nov 14, 2026
c10181a
Document the config, history, commandline, and job commands
fdncred Nov 14, 2026
9750898
Link type and reference pages to the new command sections
fdncred Nov 14, 2026
5ead855
Document the core language and help commands
fdncred Nov 15, 2026
0743d0c
Add a SQLite page and document the stor, url, and http commands
fdncred Nov 15, 2026
27b7005
Document the released parts of partly unreleased features
fdncred Nov 15, 2026
475c50a
List the new pages in the book's table of contents
fdncred Nov 15, 2026
d392499
Fix in-page links in the plugin protocol reference
fdncred Nov 15, 2026
0df6606
Correct statements an independent re-audit found wrong
fdncred Nov 15, 2026
6c8b8bf
Describe working 0.117.0 behavior instead of Nushell bugs
fdncred Nov 15, 2026
65e285f
Close the remaining documentation gaps that 0.117.0 allows
fdncred Nov 15, 2026
febc11a
Correct statements the bug-text removal left too broad
fdncred Nov 15, 2026
2089945
Check the new docs against 0.117.0 and tighten the prose
fdncred Nov 15, 2026
e3b6981
mention foreign_keys = on
fdncred Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 55 additions & 3 deletions .vuepress/configs/sidebar/en.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,17 @@ export const sidebarEn: SidebarConfig = {
children: [
'/book/types_of_data.md',
'/book/loading_data.md',
'/book/data_formats.md',
'/book/working_with_sqlite.md',
'/book/pipelines.md',
'/book/working_with_strings.md',
'/book/regular_expressions.md',
'/book/working_with_binary.md',
'/book/working_with_lists.md',
'/book/working_with_records.md',
'/book/working_with_numbers.md',
'/book/working_with_tables.md',
'/book/working_with_paths.md',
'/book/navigating_structured_data.md',
'/book/special_variables.md',
],
Expand Down Expand Up @@ -65,6 +71,7 @@ export const sidebarEn: SidebarConfig = {
'/book/sorting.md',
'/book/testing.md',
'/book/debugging.md',
'/book/language_server.md',
'/book/style_guide.md',
],
},
Expand All @@ -74,8 +81,10 @@ export const sidebarEn: SidebarConfig = {
collapsible: false,
children: [
'/book/configuration.md',
'/book/config_reference.md',
'/book/environment.md',
'/book/stdout_stderr_exit_codes.md',
'/book/terminal.md',
'/book/running_externals.md',
'/book/3rdpartyprompts.md',
'/book/directory_stack.md',
Expand Down Expand Up @@ -112,8 +121,42 @@ export const sidebarEn: SidebarConfig = {
link: '/book/advanced.md',
collapsible: false,
children: [
'/book/standard_library.md',
'/book/dataframes.md',
{
text: 'Standard Library',
link: '/book/standard_library.md',
collapsible: false,
children: [
'/book/standard_library/assert.md',
'/book/standard_library/bench.md',
'/book/standard_library/clip.md',
'/book/standard_library/config.md',
'/book/standard_library/dt.md',
'/book/standard_library/formats.md',
'/book/standard_library/help.md',
'/book/standard_library/input.md',
'/book/standard_library/iter.md',
'/book/standard_library/log.md',
'/book/standard_library/math.md',
'/book/standard_library/random.md',
'/book/standard_library/util.md',
'/book/standard_library/xml.md',
'/book/standard_library/std_rfc.md',
],
},
{
text: 'Dataframes',
link: '/book/dataframes.md',
collapsible: false,
children: [
'/book/dataframes/frames.md',
'/book/dataframes/selectors.md',
'/book/dataframes/math.md',
'/book/dataframes/strings.md',
'/book/dataframes/dates.md',
'/book/dataframes/conditionals.md',
'/book/dataframes/aggregation.md',
],
},
'/book/metadata.md',
'/book/creating_errors.md',
'/book/parallelism.md',
Expand Down Expand Up @@ -192,6 +235,7 @@ export const sidebarEn: SidebarConfig = {
collapsible: true,
children: [
'/lang-guide/chapters/types/basic_types/any.md',
'/lang-guide/chapters/types/basic_types/number.md',
'/lang-guide/chapters/types/basic_types/bool.md',
'/lang-guide/chapters/types/basic_types/int.md',
'/lang-guide/chapters/types/basic_types/float.md',
Expand All @@ -217,7 +261,10 @@ export const sidebarEn: SidebarConfig = {
{
text: 'Types used only in command signatures',
link: '/lang-guide/chapters/types/other_types/00_not_assignable.md',
children: ['/lang-guide/chapters/types/other_types/path.md'],
children: [
'/lang-guide/chapters/types/other_types/path.md',
'/lang-guide/chapters/types/other_types/external_arg.md',
],
},
{
text: 'Types which are not declarable',
Expand All @@ -242,6 +289,7 @@ export const sidebarEn: SidebarConfig = {
children: [
'/lang-guide/chapters/flow_control/if-else.md',
'/lang-guide/chapters/flow_control/loop.md',
'/lang-guide/chapters/flow_control/for.md',
'/lang-guide/chapters/flow_control/while.md',
'/lang-guide/chapters/flow_control/match.md',
'/lang-guide/chapters/flow_control/try-catch.md',
Expand All @@ -259,8 +307,12 @@ export const sidebarEn: SidebarConfig = {
'/lang-guide/chapters/filters/selecting_data.md',
'/lang-guide/chapters/filters/where-filter.md',
'/lang-guide/chapters/filters/select-get.md',
'/lang-guide/chapters/filters/changing_data.md',
'/lang-guide/chapters/filters/summarizing_lists.md',
'/lang-guide/chapters/filters/record_commands.md',
],
},
'/lang-guide/chapters/matrices.md',
'/lang-guide/chapters/custom_commands.md',
'/lang-guide/chapters/declarations.md',
'/lang-guide/chapters/variable_scope.md',
Expand Down
56 changes: 55 additions & 1 deletion book/aliases.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,63 @@ alias m = math

This is particularly handy for plugins with many subcommands. For example, after `alias pl = polars`, you can write `pl into-df`, `pl select` and `pl collect`.

## What an alias can contain

The right side of an alias is a single command call. It can include some of the command's arguments and leave the rest for the call site, even required ones:

```nu
alias r = str replace
"a-b-c" | r --all "-" "+"
# => a+b+c
```

Anything other than one command call is rejected with `nu::parser::cant_alias_expression`. That covers pipelines like `ls | length`, redirections like `echo hi o> out.txt`, math expressions, and variables or cell paths like `$nu.home-dir`:

```nu
alias total = 1 + 2
# => Error: nu::parser::cant_alias_expression
# =>
# => × Can't create alias to expression.
# => ╭─[repl_entry #1:1:15]
# => 1 │ alias total = 1 + 2
# => · ┬
# => · ╰── aliasing a binary operation is not supported
# => ╰────
# => help: Only command calls can be aliased.
```

Most parser keywords can't be aliased either. The exceptions are `if`, `match`, `try`, `overlay`, `overlay use`, `overlay new` and `overlay hide`. Aliasing any other keyword, such as `alias l = let`, is a `nu::parser::cant_alias_keyword` error.

The `=` needs a space on each side. `alias ll=ls -l` and `alias ll =ls -l` are both parse errors.

An alias is visible from the line that defines it to the end of the enclosing block. Unlike a `def`, it can't be used above its definition, and an alias defined inside a block, such as `do { alias ll = ls -l }`, is gone after the block ends.

## List All Loaded Aliases

Your useable aliases can be seen in `scope aliases` and `help aliases`.
Your useable aliases can be seen in [`scope aliases`](/commands/docs/scope_aliases.md) and [`help aliases`](/commands/docs/help_aliases.md). Both return a table with these columns:

- `name`: the alias name
- `expansion`: the command call the alias stands for
- `description`: the alias's description, explained below
- `decl_id`: a number that identifies the alias
- `aliased_decl_id`: the `decl_id` of the command the alias calls, as listed by `scope commands`, or `null` for an external command

A comment on the line above `alias` or `export alias` becomes the alias's description. Without one, the description is ``Alias for `<expansion>` ``:

```nu
# List files in long form
alias ll = ls -l
alias la = ls -a
scope aliases | where name in [ll la] | select name expansion description
# => ╭───┬──────┬───────────┬─────────────────────────╮
# => │ # │ name │ expansion │ description │
# => ├───┼──────┼───────────┼─────────────────────────┤
# => │ 0 │ la │ ls -a │ Alias for `ls -a` │
# => │ 1 │ ll │ ls -l │ List files in long form │
# => ╰───┴──────┴───────────┴─────────────────────────╯
```

`help aliases --find` keeps only the aliases whose name or description contains the given text, so `help aliases --find long` lists `ll` here. `help aliases ll` shows the help for one alias, the same as `help ll`. An unknown name is a `nu::shell::alias_not_found` error.

Running `help` on an alias shows what it expands to, followed by the help for the aliased command. For example, with an alias for a small custom command:

Expand Down
78 changes: 58 additions & 20 deletions book/background_jobs.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ next:

# Background Jobs

Nushell currently has experimental support for thread-based background jobs.
Nushell currently has experimental support for thread-based background jobs. The subcommands of [`job`](/commands/docs/job.md) start, list, and control them. `job` on its own only prints its help, which lists those subcommands.

## Spawning Jobs

Expand All @@ -29,6 +29,10 @@ open status.txt
# => i am inevitable
```

The closure runs on a copy of the caller's variables and environment, so a change it makes, such as setting `$env.FOO`, doesn't come back. Whatever the closure returns is thrown away, and so is the output of the external commands it runs. Only [`print`](/commands/docs/print.md) reaches the terminal. If the closure fails, Nushell prints the error, unless the job was killed or the [`display_errors`](./config_reference.md#display-errors) settings hide it. A job can spawn jobs of its own.

Spawn a job with `--auto-kill` (`-k`) when it is fine to stop it without notice, such as a file watcher. [Exit Behavior](#exit-behavior) explains how `exit` treats such a job.

## Listing and Killing jobs

Active jobs can be queried with the [`job list`](/commands/docs/job_list.md) command, which returns a table with the information of the jobs which are currently executing.
Expand All @@ -38,11 +42,11 @@ Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job
let id = job spawn { sleep 1day }

job list
# => ╭───┬────┬────────┬────────────────╮
# => │ # │ id │ type │ pids │
# => ├───┼────┼────────┼────────────────┤
# => │ 0 │ 2 │ thread │ [list 0 items] │
# => ╰───┴────┴────────┴────────────────╯
# => ╭───┬────┬────────┬────────────────┬───────────╮
# => │ # │ id │ type │ pids │ auto_kill │
# => ├───┼────┼────────┼────────────────┼───────────┤
# => │ 0 │ 2 │ thread │ [list 0 items] │ false │
# => ╰───┴────┴────────┴────────────────┴───────────╯

job kill $id

Expand All @@ -52,6 +56,8 @@ job list
# => ╰────────────╯
```

The `auto_kill` column says whether the job was spawned with `--auto-kill`.

## Describing jobs

To make jobs easier to tell apart, you can give a job a description when you spawn it with `job spawn --description`, or change it later with [`job describe`](/commands/docs/job_describe.md). The description is shown in an additional `description` column of `job list`:
Expand All @@ -61,15 +67,17 @@ let id = job spawn --description "long nap" { sleep 1day }
job describe $id "longer nap"

job list
# => ╭───┬────┬────────┬────────────────┬─────────────╮
# => │ # │ id │ type │ pids │ description │
# => ├───┼────┼────────┼────────────────┼─────────────┤
# => │ 0 │ 3 │ thread │ [list 0 items] │ longer nap │
# => ╰───┴────┴────────┴────────────────┴─────────────╯
# => ╭───┬────┬────────┬────────────────┬───────────┬─────────────╮
# => │ # │ id │ type │ pids │ auto_kill │ description │
# => ├───┼────┼────────┼────────────────┼───────────┼─────────────┤
# => │ 0 │ 3 │ thread │ [list 0 items] │ false │ longer nap │
# => ╰───┴────┴────────┴────────────────┴───────────┴─────────────╯

job kill $id
```

To remove a description, pass `null`, as in `job describe $id null`.

## Job suspension

On Unix targets, such as Linux and macOS, Nushell also supports suspending external commands using <kbd>Ctrl</kbd>+<kbd>Z</kbd>. When a running process is suspended, it is turned into a "frozen" background job:
Expand All @@ -79,13 +87,13 @@ On Unix targets, such as Linux and macOS, Nushell also supports suspending exter
# => Job 4 is frozen

job list
# => ╭───┬────┬────────┬──────────────┬─────────────╮
# => │ # │ id │ type │ pids │ description │
# => ├───┼────┼────────┼──────────────┼─────────────┤
# => │ 0 │ 4 │ frozen │ ╭───┬──────╮ │ sleep │
# => │ │ │ │ │ 0 │ 6337 │ │ │
# => │ │ │ │ ╰───┴──────╯ │ │
# => ╰───┴────┴────────┴──────────────┴─────────────╯
# => ╭───┬────┬────────┬──────────────┬───────────┬─────────────╮
# => │ # │ id │ type │ pids │ auto_kill │ description │
# => ├───┼────┼────────┼──────────────┼───────────┼─────────────┤
# => │ 0 │ 4 │ frozen │ ╭───┬──────╮ │ false │ sleep │
# => │ │ │ │ │ 0 │ 6337 │ │ │ │
# => │ │ │ │ ╰───┴──────╯ │ │ │
# => ╰───┴────┴────────┴──────────────┴───────────┴─────────────╯
```

A frozen job is automatically described with the name of the suspended program.
Expand Down Expand Up @@ -148,6 +156,24 @@ job recv
# => Hello from a background job
```

Inside a job, [`job id`](/commands/docs/job_id.md) returns that job's own ID. Outside any job, it returns `0`, the ID of the main thread. A job spawned from another job gets an ID of its own. When several jobs report back to the same receiver, `job id` lets each message say which job sent it:

```nu
for n in 1..3 {
job spawn { {job: (job id), result: ($n * 10)} | job send 0 }
}
1..3 | each { job recv } | sort-by job
# => ╭───┬─────┬────────╮
# => │ # │ job │ result │
# => ├───┼─────┼────────┤
# => │ 0 │ 1 │ 10 │
# => │ 1 │ 2 │ 20 │
# => │ 2 │ 3 │ 30 │
# => ╰───┴─────┴────────╯
```

The IDs depend on how many jobs the session has started before.

Messages can carry a numeric tag with `job send --tag`. `job recv --tag` then only receives messages with that tag, leaving others in the mailbox, and `job recv --timeout` stops waiting after the given duration:

```nu
Expand All @@ -160,7 +186,11 @@ job recv --timeout 0sec
# => low priority
```

To discard messages without reading them, use [`job flush`](/commands/docs/job_flush.md), which clears the whole mailbox of the current job, or only the messages with a given tag when used with `--tag`.
[`job send`](/commands/docs/job_send.md) never waits for the receiver. The message goes straight into the mailbox. Sending to a job that doesn't exist is an error, such as `Job 99 not found`.

Without `--timeout`, [`job recv`](/commands/docs/job_recv.md) waits until a matching message arrives, and <kbd>Ctrl</kbd>+<kbd>C</kbd> interrupts the wait. When the timeout runs out first, it fails with `nu::shell::job::recv_timeout`. A timeout of `0sec` succeeds only when a matching message is already in the mailbox. Inside [`par-each`](/commands/docs/par-each.md), only one thread at a time can wait in `job recv`. The other threads wait for their turn in no particular order, whatever their timeouts.

To discard messages without reading them, use [`job flush`](/commands/docs/job_flush.md), which clears the whole mailbox of the current job, or only the messages with a given tag when used with `--tag`. A message that arrives while `job flush` runs may be discarded too.

## Exit Behavior

Expand All @@ -175,7 +205,12 @@ for spawning independent background processes (see [#15201](https://github.com/n

Additionally, if the user is running an interactive Nushell session and runs
[`exit`](/commands/docs/exit.md) while there are background jobs running,
the shell will warn about them before prompting the user to confirm `exit`.
the shell doesn't exit, and it doesn't ask for confirmation either. It prints a
`nu::shell::background_jobs_running` warning with the number of running jobs, frozen jobs included,
and returns to the prompt. Running `exit` again as the next command kills the jobs and exits; if you run any other command first, the next `exit` warns again.
Jobs started with `job spawn --auto-kill` don't count toward the warning and are killed
on exit without one. A frozen job counts even when its external command was suspended
inside an auto-kill job.

Pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> at the REPL interrupts only the command running in the foreground.
Background jobs and frozen jobs keep running.
Expand All @@ -184,4 +219,7 @@ When Nushell runs a script or a command given with `nu -c`, it stops any jobs th
along with their child processes, before it exits. This also happens when the script was interrupted
with <kbd>Ctrl</kbd>+<kbd>C</kbd> and the interruption was caught.

A [`try`](./control_flow.md#try) block catches an interrupt like any other error, as
[Interrupting with Ctrl+C](./stdout_stderr_exit_codes.md#interrupting-with-ctrl-c) describes.

Calling `exit` inside a job's closure ends that job, not the shell.
Loading
Loading