Skip to content

Fully document Nushell 0.117.0 - #2294

Merged
fdncred merged 46 commits into
nushell:mainfrom
fdncred:docs-coverage
Nov 16, 2026
Merged

fdncred merged 46 commits into
nushell:mainfrom
fdncred:docs-coverage

Conversation

@fdncred

@fdncred fdncred commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Description

This PR writes hand-written docs for the Nushell 0.117.0 features that had none, or that only the generated command pages explained.

It started with an audit of every feature we could find, 1,964 in all. The list came from the source and a build of nu, not from the docs, so features the docs never mention could show up. It covers scope commands, the Config struct and the runtime $env.config keys, $nu, help operators, keybindings list, the std and std-rfc modules, the parser and plugin protocol enums, and nu --help. Each feature got one of four ratings:

  • 100%: the hand-written docs explain the feature and every detail the source has, meaning each flag, option value, variant and notable behavior.
  • some: the hand-written docs cover the feature but miss at least one detail.
  • none: nothing in the English docs, the command reference or the binary.
  • cmd-only: only the generated page in commands/docs/ covers it.

The ratings are strict. One unexplained flag keeps a feature at some.

Before and after

Before this PR, 439 of the 1,964 features (22%) were fully documented. After it, 1,930 (98%) are.

Rating Before (d619796) After (this PR)
100% 439 1,930
some 969 32
none 93 2
cmd-only 463 0
Total 1,964 1,964

By area:

Area Features 100% before 100% after
Language: data types and literals 83 33 83
Language: operators, expressions, pipelines, and externals 99 21 99
Language: custom commands, variables, modules, overlays, and scripts 119 59 115
Language: control flow, errors, and exit codes 90 48 90
Environment, special variables, and the nu executable 116 17 114
Configuration, startup, theming, and hooks 86 6 85
Interactive shell and line editor 209 57 198
Standard library 143 11 142
Plugins and dataframes 360 97 360
Tooling: LSP, MCP, DAP, explore, tui, jobs, and metadata 153 60 151
Commands: filters, generators, chart, default, and misc 108 0 104
Commands: strings, conversions, formats, math, bits, bytes, hash, date, random, and path 195 5 193
Commands: core, env, debug, experimental, shells, prompt, and history 108 23 103
Commands: filesystem, platform, system, network, viewers, and database 95 2 93
Total 1,964 439 1,930

The 34 features still below 100% depend on changes that landed on main after 0.117.0. They can be finished when those changes ship.

What's in it

  • 37 new pages.
    • A configuration reference, plus pages for data formats, SQLite, binary data, numbers, paths, the terminal and the language server.
    • A page for each standard library module and one for std-rfc.
    • Seven dataframe pages covering frames, selectors, math, strings, dates, conditionals and aggregation.
    • In the language guide, chapters on matrices, the number and external_arg types, for loops, and the commands that change data, summarize lists and work on records.
    • The sidebar lists every new page, and the book's table of contents lists the new book pages.
  • Existing pages filled in. Most of the 148 changed files are pages that already existed and gained the missing flags, edge cases and errors.
  • 38 statements the 0.117.0 binary contradicts are fixed. The audit found these in the docs as they stood, and the first commit corrects them.
  • Examples checked on the release binary. Each example's output is pasted from a real run. A final pass re-ran 1,329 of the 1,375 code blocks this PR touches on the 0.117.0 release binary, and fixed the few that differed. The other 46 need a terminal, Windows, the network or a side effect, so they were checked against the 0.117.0 source.
  • Working behavior only. The docs describe how to use each feature in a way that works in 0.117.0. They don't describe Nushell bugs. The bugs found along the way are kept in a separate list, to follow up on in nushell/nushell.
  • Three warnings stay. Each is about a design-level risk, not a defect: a plugin error, or a NUON record with a repeated key, can print the environment, secrets included; the MCP server runs any code it's given; and saving over the file being read empties it.
  • Proofreading. Independent reviewers re-checked samples of the ratings and the edits. Several passes cut repeated text and AI-sounding prose.

These passages described behavior that the 0.117.0 binary or source
contradicts. Each was re-checked before editing.

- configuration: assigning a record to $env.config merges; login.nu
  loads before the autoload dirs; -l with a script file loads no config
- hooks: display_output and command_not_found run under -c and scripts
- coloring_and_theming: drop bg_* names, which color_config ignores;
  every prompt variable accepts a closure
- line_editor: keybindings and menus assignment replaces the list
  (#19418); fix Alt+C, add PageUp/PageDown, correct the
  `keybindings default` claim
- types: inf/-inf/NaN literals; custom type names work as annotations
- strings, globs, date, =~ engine, null comparisons, multi-line
  parameter comments, module path resolution, std/dirs vs std/log,
  error chaining from catch, load-env PATH conversion, nu -i -c,
  display_output default, tui and mcp defaults, explore config saving,
  background job exit warning, alias hoisting, match int/float
  equality, reduce closure parameter order

Prettier re-padded the color table in coloring_and_theming.md after the
bg_* rows were removed.
Covers the rows rated `none` in the coverage checklist for data types,
literals, operators, redirection, and Nushell's exit status:

- quotes inside one word, nested interpolation, bare-word interpolation
- inf/-inf/NaN, inclusive ranges, range bound and construction errors
- list and record separators, parenthesized expressions in literals,
  combined cell-path modifiers, interpolated globs
- subtyping and which values a type annotation accepts
- unary minus, every redirection spelling including the append forms,
  where redirections are allowed, and nu's exit status after an error

Examples were run with a 0.117.1-dev build and checked against 0.117.0.
Covers the rows rated `none` in the coverage checklist for environment
variables, the nu executable, and startup:

- special_variables: COLUMNS/LINES, proxy variables and NO_PROXY,
  LC_ALL/LC_TIME/LANG, NU_BACKTRACE, NU_EXPERIMENTAL_OPTIONS,
  NU_VENDOR_AUTOLOAD_DIR, NUSHELL_SHELLS and friends, PATHEXT, PWD,
  SSH_CLIENT, TERM_PROGRAM, XDG_CACHE_HOME
- environment: the automatic PWD, FILE_PWD, and CURRENT_FILE variables
  and the error when you try to set or hide them
- configuration: $env.config validation errors, flag syntax for nu,
  starting the REPL without a terminal, errors and broken symlinks in
  startup files, and experimental options

Windows-only PATHEXT behavior and the build-time vendor autoload
setting were written from the 0.117.0 source; the rest was run.
Covers the rows rated `none` in the coverage checklist for the language
server, the debug adapter, explore, and plugins:

- new page book/language_server.md: starting `nu --lsp`, what it loads,
  editor setup for VS Code and Neovim, what the client must send, and
  each capability with its limits (diagnostics, completion, hover,
  signature help, definition, highlight, references, rename, symbols,
  inlay hints, semantic tokens)
- debugging: DAP pause and the nuDapVisualize request
- explore: the :table and :expand commands and the binary (hex) viewer
- plugins: the installed_plugins column of `version` and the JavaScript
  example plugin; contributor book: serve_plugin_io and
  create_plugin_signature
- dataframes: cloud storage URLs and where polars reads credentials

LSP and DAP behavior was checked with scripted clients against a
0.117.1-dev build and the 0.117.0 source. Cloud reads need credentials
and were not run.
Covers the rows rated `none` in the coverage checklist for custom
commands, modules, scripts, and control flow:

- defining a command twice in one block, duplicate parameter and flag
  names, and user-defined attributes
- what a module body may contain, and how a submodule named `mod` is
  merged into its parent
- `nu script.nu --help`
- `else`, `catch`, and `finally` must stay on the line of the closing
  brace; type annotations on the `for` variable
- `catch` and `finally` with a closure in a variable, `try` collecting
  the block's output, and re-raising a caught error with `raw`

Parse errors were captured from a REPL. The code that decides each
behavior is unchanged between 0.117.0 and the build used for testing.
Covers the rows rated `none` in the coverage checklist for the line
editor, completions, and the standard library:

- line_editor: the legacy pair edits, prefix history search with the
  arrow keys, and completion of command names with `^` and `%`, after
  sudo/doas, cell paths, operators, attributes, and module exports
- directory_stack: where std/dirs keeps the stack (DIRS_LIST and
  DIRS_POSITION)
- standard_library: null_device, std/log formats, placeholders, and
  level commands, and std-rfc/kv universal variables
- testing: the testing.nu runner, including the --module workaround
- custom_completions: checking suggestions with `commandline complete`

REPL behavior was driven through expect; history search details for vi
and helix modes and the Windows null device come from the source.
Covers the rows rated `some` in the coverage checklist for custom
commands, signatures, attributes, variables, constants, and aliases:

- custom_commands: streaming and collecting input, naming rules,
  optional/default/rest/flag rules including the null-default trap,
  the full list of parameter types, list and const completers,
  `--wrapped`, the reserved `--help` flag, and attribute syntax
  (@example, @deprecated, @category)
- lang-guide: definition and signature errors, `scope commands` and
  signature columns, runtime type checks, compound assignment, which
  commands run at parse time, and `type` alias errors
- variables and aliases: `let` after a pipe, cell-path assignment,
  `unlet` on a const, what an alias may contain, alias scope and
  descriptions

40 of the 45 rows are now fully documented; the rest wait on pages
owned by other parts of the checklist or on post-0.117.0 changes.
Covers the rows rated `some` in the coverage checklist for data types,
literals, annotations, and type signatures:

- int, float, duration, filesize, binary, datetime, range: literal
  rules and spellings, operators and their errors, conversions,
  rounding, and how file sizes and dates are displayed and formatted
- custom values: annotations, `into value`, plugin custom values,
  semver, semver ranges, and matrices
- new pages for the `number` and `external_arg` types, and a fix to
  the not-assignable types page, which said every annotated variable
  behaves like `string`
- bool.md no longer lists the regex and starts-with/ends-with
  operators as bool operators
- the octal example in types_of_data.md was a parse error

The new pages are added to the sidebar.
Covers the rows rated `some` in the coverage checklist for startup
files, `$env.config` update semantics, config commands, and the
display and behavior settings that only `config nu --doc` described:

- new page book/config_reference.md: every `$env.config` key in
  0.117.0, grouped as `config nu --doc` groups them, with its type,
  default, accepted values, behavior, and a verified example
- configuration: first-run messages, `config reset` after config.nu is
  deleted, editor lookup order, autoload directories, PATH lookup and
  `path add`, the default prompt, `config nu/env --doc/--default`,
  XDG variable handling, a table of every `nu` flag, and corrected
  launch-stage rows

Where `config nu --doc` disagrees with the binary (the "KB" unit, tabs
in ignore_space_prefixed, `~` in history.path, stream_page_size and
collect), the new page follows the binary.
Covers the rows rated `some` in the coverage checklist for operators,
precedence and type rules, and the "coming from" pages:

- operators: older-than/newer-than, associativity, subexpressions,
  operators in command arguments, comparing datetimes, regex details
  and errors, and spread errors and null spreads
- lang-guide operators: types, edge cases, and errors for each
  operator group, with the precedence numbers from `help operators`
- nushell_operator_map: every operator `help operators` prints; the
  `=~`/`like` row was wrong in the SQL and PowerShell columns
- thinking_in_nu: a lone `>` is an argument, the parse errors for
  `&&`, `||`, `2>`, and `2>&1`, `echo` return values, and `o>` as an
  alternative to `save`
- coming_from_bash and coming_from_cmd: more command equivalents,
  `which` output, history expansion, and how `start` picks an opener
Covers the rows rated `some` in the coverage checklist for environment
variables, `$nu` fields, special variables, and nu's flags:

- special_variables: the `$nu` path fields and their override flags,
  os-info, startup-time, is-lsp; CURRENT_FILE, FILE_PWD, path self,
  LAST_EXIT_CODE, CMD_DURATION_MS, PATH, PROCESS_PATH, SHLVL,
  NU_LIB_DIRS, NU_LOG_LEVEL, HOME, RUST_BACKTRACE, and `$ans`
- environment: load-env and `A=1 cmd` prefixes with conversions,
  case-preserving updates, ENV_CONVERSIONS key spelling and failures,
  `config env-conversions`, what externals receive, and hide-env
- default_shell and setup: where `/c` is recognized, and `exec nu` on
  Windows

Flag details link to the `nu` flags and experimental options sections
of configuration.md instead of repeating them.
Covers the rows rated `some` in the coverage checklist for plugin
installation and management, the registry, configuration, garbage
collection, custom values, the protocol, and writing plugins:

- plugins: how `plugin add` finds and names a plugin, --plugin-config,
  `nu --plugins`, the search path and registry file, version-mismatch
  errors, `plugin list` columns, `plugin stop`/`rm`, GC edge cases,
  `$env.config.plugins`, and the Polars value types
- contributor book: local sockets, optional PluginCommand methods,
  LabeledError and EvaluatedCall helpers, byte streams, when input
  streams end, custom value methods, PluginTest, and the example
  plugins
- protocol reference: GetCompletion and CompletionItems, every
  Signature field, GetPluginConfig errors, the Config and Operator
  shapes, engine call methods, and a rewritten IrBlock section (its
  example used an `ast` field that 0.117.0 removed)
- `plugin use`, `rm`, and `stop` look for a filename in the current
  directory only, not in NU_PLUGIN_DIRS; `plugin rm` accepts a
  filename

The configuration reference now links the plugin settings section.
Covers the rows rated `some` in the coverage checklist for pipelines,
output display, stdout/stderr/exit codes, external commands, and
`extern`:

- stdout_stderr_exit_codes: display_errors settings and SIGPIPE, what
  changes with pipefail off, `exit` and nu's exit status, Ctrl+C in
  the REPL and in scripts, `complete` with non-UTF-8 output, `print`
  and redirections, redirection targets, `ignore`, `is-terminal` and
  `is-redirected`, and `decode`
- pipelines: line continuation, `let` as a pipeline stage, `$in` as an
  argument, `collect`, the trailing newline trimmed from external
  output, `lines`, `to text`, and `sleep`
- running_externals: name resolution and not-found hints, quoting and
  interpolation in bare words, value conversion, spreads, `^(expr)`,
  `--` passing through, and Windows argument rules
- externs: quoted multi-word names, how flags reach the command, and
  `--strict`
- how_nushell_code_gets_run: `view ir` options, what `source-env`
  keeps, and a link to the language server page

`collect --keep-env` has no effect in 0.117.0 and is left out.
Covers the rows rated `some` in the coverage checklist for
color_config keys, style syntax, themes, and hooks:

- coloring_and_theming: the `_blink` and `_strike` color names, which
  keys Nushell uses or ignores, footers and float precision, turning
  colors on and off (use_ansi_coloring, FORCE_COLOR, NO_COLOR,
  CLICOLOR, TERM), xterm color names, the built-in LS_COLORS, the std
  themes, and `ansi gradient`
- the comment under the color table explained how to regenerate it
  with `ansi --list`, which can't produce it; it now says why
- closures do work as values in a list, and the
  leading_trailing_space_bg examples now set a background
- hooks: hook lists and errors, the command_not_found hook, the first
  env_change call with `$before` as null, hook parameters, record and
  string hooks, the display_output default, and `commandline` from a
  keybinding
Covers the rows rated `some` in the coverage checklist for the std-rfc
modules, which only their `--help` text described:

- book/standard_library/std_rfc.md: what std-rfc is and how stable it
  is, how to import each module (and what `use std-rfc *` changes),
  and a section for each of conversions, date, iter, kv, path, pb,
  random, str, tables, url, and xml with parameters, behavior, edge
  cases, and examples
- the kv section covers universal variables, including the current
  bugs with an empty store, child processes, and removals

Every code block on the page was run as written. The page is added to
the sidebar under the standard library chapter.
Covers the rows rated `some` in the coverage checklist for completers,
suggestion records, built-in completion sources, and completion
settings:

- custom_completions: ways to attach a completer (lists, consts,
  records, aliases), built-in sources including file and directory
  names, how a parameter completer and a command-wide completer take
  turns, the suggestion fields kind, append_whitespace, and
  match_indices, span edge cases, when an external completer is
  interactive, `commandline complete` from a keybinding, and the
  completions settings (algorithm, sort, case_sensitive, quick,
  partial, use_ls_colors, external)
- corrections: `null` from a completer falls through to the
  command-wide completer, a failing parameter completer offers
  nothing, and `filter: true` only sorts for @complete completers
- external_completers: an fzf picker recipe using @Interactive

Completer caching is left out; its behavior changes after 0.117.0.
Covers the rows rated `some` in the coverage checklist for strings,
string interpolation, regular expressions, and cell paths:

- working_with_strings: multi-line quotes, escapes and their errors,
  which bare words become other types, backtick strings, run-external
  and strings as commands, how values are written into interpolated
  strings, the split commands, str join/index-of/substring and byte
  versus grapheme counts, fill, str reverse, replacing text, parse,
  from csv/tsv/ssv options, into string, char, and ansi
- lang-guide strings_and_text: escape errors, single-quote rules,
  backtick strings, nested quotes, and bare-word rules
- regular_expressions: inline flags, group references in str replace,
  --no-expand, --multiline, closure replacements, parse --regex column
  names and unmatched groups, and --backtrack
- navigating_structured_data: numeric record keys only need quotes in
  a cell path, how record keys are written, and `default`

The regular expressions page is added to the sidebar after Working
with Strings.
Covers the rows rated `some` in the coverage checklist for the Polars
plugin and the Polars commands the chapter already mentions:

- reading options for `polars open`, including the Hive flags
- the plugin's object store, grouping keys and aggregations, how
  values become columns, series and expression operators, and when
  results are eager or lazy
- join flags, `polars sum`, renaming, with-column, cell paths, masks,
  indices, and unique values
- new task sections for selecting rows and columns, sorting, and
  working with strings
- `polars collect` returns an eager dataframe, not a Nushell table,
  and not every operation works on both eager and lazy frames
- `bench` options

Examples were run with nu_plugin_polars 0.117.0 in a scratch plugin
registry. Plugin bugs the examples ran into are described as current
behavior, with workarounds where there are any.
Covers the rows rated `some` in the coverage checklist for filter
commands, generators, `chart`, `default`, and related commands:

- new lang-guide pages: "Adding and changing data" (append, prepend,
  insert, update, upsert, move, rename, merge, join, flatten, wrap,
  transpose), "Summarizing and comparing lists" (all, any, length,
  is-empty, reduce, math sum/avg, uniq, set operations, chunks,
  combinations, permutations), and the `record` commands
- where-filter, selecting_data, select-get, each-par-each: exact rules
  for row conditions and null operands, get/select edge cases, each
  while, and SQLite query pushdown
- working_with_tables: every `table` option with examples, ansi strip
  with cell paths, join/merge/move/rename/upsert notes
- sorting: reverse sorting, `sort-by -i -n`, and sort-by rejecting
  records
- bool.md lists `record where` and explains how chunk-by uses its
  closure; operators.md links the null operand rules

The new pages are added to the sidebar under Filters.
Covers the rows rated `some` in the coverage checklist for pipeline
metadata, view commands, debugging helpers, MIME types, par-each, the
debug adapter, and the --ide-* flags:

- metadata: the data source, `metadata set` with a closure, which
  commands set path_columns, table_width_priority_columns, and peek
- mime_types: the type each `to` command sets, how `open` picks a type
  from the extension, which commands clear it, and `http delete`
- helpers_and_debugging: describe, debug, debug env/info, inspect,
  scope variables, ast, explain, the view commands, timeit, and debug
  profile (whose --expand-source flag does nothing in 0.117.0)
- parallelism: par-each thread count, dropped null results,
  --keep-order, and thread pool reuse
- debugging: VS Code setup and launch.json, why Zed can't use the
  adapter, breakpoint and logpoint edge cases, and variable limits
- language_server: the one-shot --ide-* flags with real output
Covers the rows rated `some` in the coverage checklist for `explore`,
the `tui` commands, the MCP server, and background jobs:

- mcp: transports and --mcp-transport validation, every tool and its
  errors, structuredContent, history eviction, the output limit,
  promoting long calls to jobs, allowed hosts, server instructions,
  NU_MCP_* variables, and what the debug log contains
- explore: views, search, quit keys, command history, :help, :nu,
  :try, --peek, status colors, `explore config` editing and saving,
  and `explore regex`
- tui: textbox keys, tree --walk, bind key names, input list, and
  nu-highlight options
- background_jobs: frozen jobs, the exit warning, job send/recv/flush
  rules, and Ctrl+C inside `try`

MCP behavior was driven over stdio and HTTP; explore, tui, and the REPL
cases were driven in tmux.
Covers the rows rated `some` in the coverage checklist for the `std`
library, whose commands have no generated reference pages:

- new pages under book/standard_library/ for assert, bench, clip,
  config, dt, formats, help, input, iter, log, math, random, util, and
  xml, each with the module's commands, parameters, behavior, edge
  cases, and examples
- standard_library is now the overview: a module table linking each
  page, the prelude, `use std` versus `use std *`, --no-std-lib, and
  the export-env caveat; the log, clip, and null_device material moved
  to the module pages
- testing: --error-labels, how the test attributes work, and skipped
  tests
- directory_stack: how `dirs add`, `drop`, `next`, `prev`, and `goto`
  behave at the edges, and the invalid index error

Links in stdout_stderr_exit_codes and custom_commands now point at the
new pages. The module pages are added to the sidebar ahead of std-rfc.
Covers the rows rated `some` in the coverage checklist for opening and
saving data, formats, the filesystem commands, system commands, and
HTTP:

- loading_data: what each loading command returns, a table of every
  format with its read and write commands (including dotenv and the
  plugin formats), TOML notes, opening several files, and saving data,
  with a warning about `open f | ... | save -f f`
- moving_around and cookbook/files: ls, cd, cp, mv, rm, mkdir, glob
  and the wax engine, glob expansion in external arguments, and the
  0.117.0 uutils message quirk
- cookbook/http: headers and credentials, error responses, --full,
  redirects and timeouts, how request bodies are sent, put, patch, and
  delete, and certificates, proxies, and pooling
- cheat_sheet: a Dates section; cookbook system, help, git, and
  parsing: smaller gaps and links

HTTP examples ran against local servers only.
Covers the rows rated `some` in the coverage checklist for modules,
overlays, scripts, control flow, error display settings, and creating
errors:

- modules: import forms, export lists, `use` paths and errors, hiding,
  and ndjson open/save notes
- overlays: overlay new/use/hide flags, prefixes, and how hiding an
  overlay restores the directory it was activated from
- scripts: `def main` rules, `run` resolving relative paths from the
  calling file, and top-level `return`
- control_flow and lang-guide flow_control: if/else and match rules,
  loops, a new `for` page, `return`, `try`/`catch` details including
  Ctrl+C inside `try`, and display_errors settings
- creating_errors: more `error make` fields and storing an error for
  later

Examples that behave differently on later builds (module reload,
`do -i` with `exit`) were checked against the official 0.117.0 release
binary. The `for` page is added to the sidebar after `loop`.
Covers the rows rated `some` in the coverage checklist for the line
editor: multi-line editing, edit modes, keybindings, events and edit
commands, menus, history, hints, the status line, abbreviations, and
terminal integration:

- a reference section at the end of the page: terminal integration
  settings (shell_integration, bracketed_paste, use_kitty_protocol)
  and tables of every event and edit command, including when each
  falls through in `until`
- multi-line input rules, Ctrl+O editor placeholders, cursor_shape
  defaults, Ctrl+D with background jobs, the cut buffer, vi pending
  keys and visual mode, Helix counts, select mode, and match mode
- keybinding fields and validation, `keybindings list/default/listen`,
  `event: null` versus `send: none`
- menus: required fields, validation, persistent menus, IDE options,
  description_position, and extra suggestion fields
- completion of subcommands and flags, history max_size, reverse
  search, hint matching and errors, status line truncation, and where
  abbreviations expand
- input_listen_keys: the records `input listen` returns

REPL behavior was driven in tmux and checked against the 0.117.0 and
reedline v0.53.0 sources.
Covers the rows rated `cmd-only` in the coverage checklist for the
`bytes`, `bits`, and `hash` commands, and the leftover `into binary`
row:

- new page book/working_with_binary.md: what binary values are and how
  to get them, how they display, list commands on binary, the `bytes`
  commands (which stream and which collect, building, slicing,
  searching, editing, splitting), the `bits` commands (endian padding,
  word size and sign, shifts, rotations, overflow), and `hash`
- lang-guide binary.md: the `into binary` byte layout, --endian and
  --compact edge cases, operators, and links to the new page

`bits not` on a non-negative int with an 8-byte word keeps only 47
bits in 0.117.0; the page warns about it. The new page is added to the
sidebar after Regular Expressions.
Covers the rows rated `cmd-only` in the coverage checklist for the
`math` and `random` commands, `date humanize`, `date list-timezone`,
`into duration`, `into filesize`, `into float`, and `format duration`:

- new page book/working_with_numbers.md: a table of what each `math`
  command accepts (ints, floats, durations, file sizes, ranges, records
  and tables with cell paths, empty input), which run in `const`, each
  command's edge cases and domain errors, and the `random` commands and
  how they relate to `shuffle`, std/random, and std-rfc/random
- lang-guide int, float, duration, filesize, datetime: converting to
  each type, formatting durations, and an overview of the `date`
  commands
- cheat_sheet: a Numbers section

The new page is added to the sidebar after Working with Records.
Covers the rows rated `cmd-only` in the coverage checklist for the
filesystem, platform, system, and path commands, plus the leftover
`path join` and `path dirname` rows:

- new page book/working_with_paths.md: the `path` commands, which
  inputs each accepts (only `path join` takes records and lists of
  parts), and their errors
- new page book/terminal.md: `term size` and `term query`, `clear`,
  `grid`, `ansi link`, and `ansi opt`
- moving_around: `touch` and `mktemp`; cookbook/files: a `watch` recipe
  and the `idx` commands including `idx watch`
- cookbook/system: the `sys` subcommands, `uname`, `whoami`, `ulimit`
  (whose -S and -H are swapped without a resource flag in 0.117.0),
  `umask`, `registry query`, `version check`, and generating
  completions for an external command
- stdout_stderr_exit_codes: `is-redirected`, and `do -i` doesn't help
  when its output goes to `let` or a pipe

Windows-only behavior was written from the 0.117.0 source. Both new
pages are added to the sidebar.
Covers the rows rated `cmd-only` in the coverage checklist for filter
commands, generators, and the `matrix` commands:

- new lang-guide chapter matrices.md: creating matrices, shape,
  indexing, reshape and transpose, element-wise operators versus
  `matrix add`/`subtract`/`scale` with broadcasting, shape-mismatch
  errors, `matrix multiply`, rows and columns, sum/mean/max, `matrix
  map`/`reduce`, and converting back
- changing_data: update cells, merge deep (with its four strategies),
  zip, interleave, rotate, and roll
- summarizing_lists: is-not-empty, uniq-by, chunk-by, split list, and
  window; selecting_data: every, columns, and values
- sorting: random order with `shuffle`; working_with_lists: `seq`;
  cookbook/tables: calendar tables with `cal`

`matrix set-row` panics on matrices with three or more dimensions in
0.117.0; the chapter warns about it. The chapter is added to the
sidebar after the Filters group.
Covers the rows rated `cmd-only` in the coverage checklist for the
remaining string commands, conversions, and semver commands:

- working_with_strings: changing case (including the deprecated
  `str upcase`/`downcase` and the naming-convention commands),
  `str expand`, `str stats`, `str starts-with`/`ends-with` versus the
  operators, `str distance`, the `format` family, and `format number`
- regular_expressions: matching text literally with `str escape-regex`
- lang-guide bool, record, cellpath: `into bool`, `into record`, and
  `split cell-path`
- custom_value: bumping semver versions, semver range operators and
  errors, and `matrix into-nu` (a one-dimensional matrix comes back as
  one row, and --as-records only works for two dimensions); how
  `into matrix` reads a table's columns
- types_of_data: `semver bump`, and a link to the binary data page
Covers the rows rated `cmd-only` in the coverage checklist for the
commands of the official plugins other than Polars:

- a new "Using the core plugins" section of book/plugins.md with a
  subsection per plugin: formats (`from eml`, `from ics`, `from ini`,
  `from plist`, `from vcf`, `to plist`), gstat with a prompt example,
  query (`query json`, `query xml`, `query web`, `query
  webpage-info`), and inc; polars points at the dataframes chapter
- the bare `plugin` command

Examples were run with the 0.117.0 plugins in a scratch plugin
registry. Plugin crashes the examples ran into are described with a
workaround.
Covers the rows rated `cmd-only` in the coverage checklist for the
Polars plugin commands, about 160 of them:

- seven new pages under book/dataframes/: Dataframe Operations
  (combining, reshaping, nulls and duplicates, column types, binning,
  sampling, inspection, `polars query`, and `polars map-batches`),
  Column Selectors, Math Expressions, String Expressions, Dates and
  Times, Masks and Conditionals, and Aggregations and Window Functions
- dataframes.md: saving dataframes (with a warning about saving a lazy
  frame over its source), `store-get`/`store-rm`, `join-where`,
  `into-nu` flags, more row and column selection commands, which
  commands return eager or lazy results, and an index of the new pages
- cookbook: `polars append`

Every example was run with nu_plugin_polars 0.117.0 loaded through
`--plugins`. The pages describe the plugin bugs the examples ran into
as current behavior. The chapter becomes a sidebar group with the new
pages as children.
Covers the rows rated `cmd-only` in the coverage checklist for the
`from` and `to` format commands and the `encode`/`decode` commands,
plus the leftover `from json --objects/--strict` row:

- new page book/data_formats.md: writing CSV and TSV, dotenv,
  MessagePack and msgpackz, xlsx and ods, URL query strings, XML in
  both directions, HTML, plain text, the base64/base32/base32hex/hex
  encoders, and character encodings with `encode`
- loading_data: format names in the table link to their notes; JSON
  (relaxed syntax, --strict, --objects), `from nuon`, `to md`,
  `to kdl`, `to toml`, and `yml`; `save` passes binary values to the
  matching `to` command, so piping `to msgpack` into `save x.msgpack`
  encodes twice
- cookbook/parsing: the `detect` commands

typos.toml gains `caf`, which appears in hex dump output. The new page
is added to the sidebar after Loading Data.
Covers the rows rated `cmd-only` in the coverage checklist for shell
commands and settings:

- configuration: a section on the `config` commands (`config default`,
  `config flatten`, which gives each list item a numeric key, and
  `config reset` with its timestamped backups), and the
  `debug experimental-options` and `version` columns
- config_reference: `config use-colors`, and `rm.always_trash` on
  builds without trash support
- line_editor: the `history` commands, changing the line from Nushell
  code with the `commandline` subcommands, the bare `keybindings` and
  `abbr` parents, and `generate completions`
- hooks: an edit made with `commandline edit` in a pre_execution hook
  is discarded
- special_variables: GH_TOKEN/GITHUB_TOKEN, OLDPWD, `panic`, and the
  negative signal number in exit codes; environment: OLDPWD and
  load-env with an ENV_CONVERSIONS key
- background_jobs: `job` and `job id`; quick_tour: `tutor`

REPL behavior was driven in a pseudo-terminal.
Small cross-links suggested by the writers of the earlier commits:
`seq` from the range type, `is-not-empty` from bool and string,
`interleave` from closure, the `watch` recipe from the cheat sheet,
and generating completions for an external command from the custom
completions page.
Covers the rows rated `cmd-only` in the coverage checklist for core
language commands and the help, scope, and view commands:

- creating_errors: the `error` namespace, `code` and `src` rules,
  mixing labels with `src` (and the `inner` workaround), `-u`, and
  `error make` with no argument
- scripts: `source-env`, checking a script with `nu-check`, and
  `is-admin`; running_externals: `run-internal`
- modules and overlays: `use null`, hiding names that match nothing,
  what `export` does, `export alias` with a private command, the
  `overlay` namespace, and reloading an overlay
- custom_commands: `@search-terms` and the `attr` namespace;
  declarations: a section on comment syntax
- helpers_and_debugging: `scope`, `scope externs`, `scope engine-stats`,
  and bare `view`; cookbook/help: the `help` subcommands
- pipelines: `do -i` versus `complete`, and negative signal numbers in
  `exit_code`; externs: `--strict` after the name

Version-sensitive examples were run on both the 0.117.0 release and
the development build.
Covers the rows rated `cmd-only` in the coverage checklist for the
database and network commands, plus the leftover `stor` row:

- new page book/working_with_sqlite.md: database files versus the
  in-memory `stor` database, how long the in-memory database lasts
  (one per process, shared with par-each and job spawn), every `stor`
  subcommand and its errors, the column types `stor create` declares
  and how values come back, export/import and ATTACH, and `schema`
- cookbook/http: bare `http`, `http head` and `http options`, `port`,
  the six `url` commands, an `http delete` example, the `:port/path`
  shorthand, `from json --objects` for streamed JSON, and a corrected
  description of how a pool and --redirect-mode interact
- loading_data, configuration, and the not-declarable types page link
  to the new page

The new page is added to the sidebar after Data Formats.
Covers rows rated `some` in the coverage checklist that earlier passes
skipped because part of the row changed after 0.117.0, plus a few small
gaps. Everything here is 0.117.0 behavior, checked with the 0.117.0
release binary:

- datetime: `into datetime` flags, accepted string forms, and integer
  input; `seq date` flags (whose --reverse with --days or --periods
  returns two extra dates)
- loading_data: `to json` flags and how datetimes, durations, and file
  sizes are encoded
- pipelines: `tee`, `skip until`/`skip while`, what an external's stdin
  receives for each kind of value, and `collect --keep-env` having no
  effect
- terminal: `input` and its flags; `commandline set-prompt`
- custom_commands: recursion, mutual recursion, and recursion_limit
- configuration: `--experimental-options` list forms and what a bad
  value does; startup details by mode
- modules: a path `use` re-reads the files, while a bare name keeps the
  loaded copy (the old note said directory modules were never re-read)
- cookbook/system: how `generate completions --source all` merges
  sources and when the help source runs a subcommand's --help;
  cookbook/http: --raw
- helpers_and_debugging: `view source`
Adds the pages created on this branch to book/table_of_contents.md in
the same places the sidebar has them, and moves Regular Expressions
under Nu Fundamentals to match the sidebar. The language server and
configuration reference pages get title-case titles like the other
book pages.
Links to `#value`, `#evaluatedcall`, `#enginecall-context`, and
`#bytestreamtype` pointed at headings that don't exist. They now point
to "Value types", the `Run` plugin call (which defines EvaluatedCall),
and `EngineCall`; the ByteStreamType mention has no section to link,
so it is plain code. Most of these links predate this branch.
A second reviewer checked a sample of the new text against the 0.117.0
source and binary and found these statements wrong:

- special_variables: RUST_BACKTRACE=full prints the same frames as 1
  with the release builds
- plugins: a plugin inherits stderr from the `nu` process; nothing is
  redirected through Nu
- line_editor: user-defined attributes are aliases such as
  `alias "attr my-tag" = echo`; a `def` can't back an attribute
- custom_commands: @deprecated warns when a call is parsed, even if it
  never runs
- loading_data: `to kdl --format nodes` writes a `{value, type}`
  record as an annotated value
- plugin protocol reference: the signal handler example used
  println!, which would corrupt the protocol on stdout; it now uses
  eprintln!

Three of these predate this branch.
The writing pass wrote suspected Nushell bugs into the docs as warnings,
"the help says X, but" notes, crash notes and workarounds. Take that
commentary out so each page says how to use the feature in a way that
works in 0.117.0. Where a workaround existed, it is now the plain
instruction. Flags that do nothing in 0.117.0 are no longer described,
and examples whose point was a bug are gone.

The bugs themselves are listed outside the repo for investigation.

Add one warning to the plugin docs and one sentence to `semver bump -b`:
errors from those can print the environment variables of the nu process,
which can include secrets.
Cover the details the checklist still listed as missing for features
whose behavior is released in 0.117.0, including those the independent
re-audit found:

- Language and filters: return inside a sourced file, implicit input
  reaching only the first pipeline of a body, text after a closing
  quote or record, overlay new --reload, @deprecated timing and --report,
  and the remaining edge cases of any, find, rotate, into int,
  into string and to kdl.
- Environment and tooling: the FOO=bar shorthand rules, NU_LIB_DIRS
  resolution, the exit status of an interactive nu, the order of
  experimental options, RUST_BACKTRACE values, Ctrl+C in reverse
  search, ls.clickable_links columns, the MCP server instructions, and
  Helix and Zed setup for nu --lsp.
- Plugins and std: plugin commands in which and help, signal handling
  in plugins, tracing plugin I/O with --log-level trace and
  trace_nu_plugin, to ndjson edge cases, url with-fragment encoding,
  and the polars into-dtype type names, polars query CAST types and
  operators, and polars rolling errors.

Behavior that looked like a bug was left out of the docs.
An independent review of the bug-text commit found passages that became
false once the bug remarks were taken out, because a general statement
no longer had its exception next to it. Narrow those statements so they
are true on 0.117.0, or give the setting that works:

- clip: turning the resident thread off needs both settings
- CURRENT_FILE and FILE_PWD outside script, source and use
- random pass length with few character kinds
- view source --dependencies and typed constants
- into bool on floats, bits not word sizes
- polars fill-nan on lazy input, SQL count, str-slice --length
- detect columns --ignore-box-chars, input display --types
- nu -I with Windows drive letters, format duration precision
Run the code blocks the branch added on the 0.117.0 release binary and
fix the statements and examples that didn't match: defaults, error
texts, narrow conditions, and a few examples whose output or line
numbers were off. Behavior that needs a terminal, Windows, the network
or a side effect was checked against the 0.117.0 source.

Cut repeated text and padding without dropping documented details, and
fix pages that repeated a corrected claim. The interactive completer
example now returns `options: {filter: false}`, so a fuzzy pick isn't
dropped, and the NUON section warns that the repeated-key error can
print environment variables.
@hustcer

hustcer commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Thanks for this PR! I've been looking forward to these documentation improvements for quite some time. I noticed two things that might be worth double-checking:

  • The documentation states that the in-memory SQLite database enforces foreign key constraints and that inserting a row referencing a non-existent parent will fail with FOREIGN KEY constraint failed.
    However, in Nushell 0.117.0, open_connection_in_memory_custom() does not explicitly enable foreign key enforcement with PRAGMA foreign_keys = ON. Since SQLite disables foreign key enforcement by default, the documented example may succeed instead of producing the expected error.
  • In Nushell 0.117.0, stor reset executes PRAGMA foreign_keys = OFF before dropping tables, then executes PRAGMA foreign_keys = ON afterward, regardless of the connection's previous setting.
    However, the shared in-memory SQLite connection is initially created without explicitly enabling foreign key enforcement. As a result, running stor reset can change the connection's behavior: foreign key constraints that were previously unenforced become enforced afterward.

@fdncred

fdncred commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Thanks. I'll look into it. Let me know if you see anything else that seems wrong.

@fdncred

fdncred commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

@hustcer Thanks for checking! I'm pretty sure that nushell builds rusqlite with the bundled feature, and libsqlite3-sys compiles the bundled SQLite with -DSQLITE_DEFAULT_FOREIGN_KEYS=1, so foreign keys are on by default on every connection, including the stor in-memory one. On a fresh session stor open | query db "pragma foreign_keys" returns 1, the pets example fails with FOREIGN KEY constraint failed, and stor reset leaves the setting at 1. You're right that reset forces it back on even if someone turned it off with query db; I will mention this in the sqlite/stor parts.

@fdncred
fdncred merged commit 7979e92 into nushell:main Nov 16, 2026
2 checks passed
@fdncred
fdncred deleted the docs-coverage branch November 16, 2026 21:26
@fdncred fdncred changed the title Fix doc statements that contradict Nushell 0.117.0 Fully document Nushell 0.117.0 Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants