Repository navigation
Fully document Nushell 0.117.0 - #2294
Conversation
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.
|
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:
|
|
Thanks. I'll look into it. Let me know if you see anything else that seems wrong. |
|
@hustcer Thanks for checking! I'm pretty sure that nushell builds rusqlite with the |
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 coversscope commands, theConfigstruct and the runtime$env.configkeys,$nu,help operators,keybindings list, thestdandstd-rfcmodules, the parser and plugin protocol enums, andnu --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 incommands/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.
100%somenonecmd-onlyBy area:
100%before100%afterThe 34 features still below
100%depend on changes that landed onmainafter 0.117.0. They can be finished when those changes ship.What's in it
std-rfc.numberandexternal_argtypes,forloops, and the commands that change data, summarize lists and work on records.