- commit
- 220a4790ccabcb85b9700f31b25a02a26b07149f
- parent
- 2cd4cbeb314e0eec1d22ce2cb6ecd97f6a4cb567
- author
- Dami <dami.etoile@gmail.com>
- kind
- docs risk score 0.1 of 3, Jev's estimate
| M | docs/ | 338 | ++++++++++++++++++------------ |
@@ -5,174 +5,252 @@ sidebar_position: 3
55 66 # Notebooks77 8-A notebook is a sheet where you type nushell pipelines and each one's9-table lands in the grid, named, typed and kept live. Written like a10-REPL, kept like a spreadsheet.8+A notebook is a tab of the workbook, beside its sheets, that holds cells9+rather than a grid: code cells of nushell, each with its output under it,10+and note cells of Markdown. You run the cells you choose, in the order11+you choose, as in Jupyter; any output can go to a sheet, where formulas,12+charts and pivots read it and it follows the cell's next run.1113 1214 ```nu13-sales = open sales.csv | where Region in [North South] | select Region Quarter Units14-$sales | where Units > 250 | sort-by Units --reverse15+files = ls | where type == file16+$files | where size > 1kb | sort-by size --reverse1517 ```1618 17-19+1820 19-`012 nu` opens one, at its prompt:21+Open one from a shell with `012 nu`, or from nushell with `sheet nu`22+(`sheet` is 012's nushell module: [Pipelines](pipelines.md)):2023 2124 ```sh22-012 nu # a new notebook23-012 nu work.012 # open one, or make it25+012 nu # a new notebook, its first cell ready to type in26+012 nu work.012 # the workbook's notebook, made if it has none2427 ```2528 26-In any workbook, **Data > Shell** (or the palette, or `!` on a notebook27-sheet) opens the same prompt, writing into the workbook's notebook28-sheet, or a new one named Shell 1 at the first command. On other sheets29-`!` starts an entry, as typing does. Commands run `nu` as a separate30-process, so [nushell](https://www.nushell.sh/book/installation.html)31-must be installed; without it, the prompt says so and the rest of 01229+In any workbook, **Data > Notebook > Open notebook** (or the palette)30+shows the workbook's notebook, or adds one after the sheet shown. A31+notebook's tab is marked `❯`. Cells run `nu` as a separate process, so32+[nushell](https://www.nushell.sh/book/installation.html) must be33+installed; without it, a cell's output says so and the rest of 0123234 works as before.3335 34-## The prompt36+## Cells3537 36-The formula bar becomes `nu❯`, and the mode indicator says `NU`:38+A cell is its head, its source and, for a code cell, its output:3739 38-| Key | Does |39-|---|---|40-| Enter | Run the line; the prompt stays open for the next |41-| Tab, Shift+Tab | Complete the word at the caret: a region (`$r1`) or one of nu's commands, from the box under the context line; again for the next |42-| Up, Down | The workbook's earlier lines, those starting with what's typed; the last 100 are saved with the file |43-| Esc | Stop the command running; otherwise, back to the grid |44-45-A name and `=` before the pipeline name the region; without one it's46-`r1`, `r2` and so on:47-48-```nu49-sizes = ls | select name size40+```41+ [2] big ✓ <1s42+│ big = $files | where size > 1kb43+│ | sort-by size --reverse44+ name size45+ README.md 9.8 kB46+ 012 4.2 kB5047 ```5148 52-A name is letters, digits and `_`, not starting with a digit, as a53-nushell [variable's](https://www.nushell.sh/book/variables.html) is;54-`in`, `env`, `nu` and `it` are nushell's own. Typing a name that exists55-gives that region a new command and runs it again, as does F2 on its56-label.57-58-## Regions59-60-Each command's table is a region: a label line with its name and61-command, dimmed and underlined as wide as the table, then the table,62-its first row the column names. Regions stack down the sheet in the63-order they ran, a row between them; when a table grows or shrinks, the64-rows below it move, as if you'd inserted or deleted rows.65-66-A region is still cells of the grid. Its values are67-[typed](types.md) (file sizes in the Size format, durations, dates),68-formulas read them, and you can format them, filter them69-(**Data > Create a filter**), sort them (the sort is kept, so the table70-stays sorted when it runs again) and chart them. Like an71-[array's spill](../formulas/arrays.md#spilled-cells), they can't be72-typed over: change the command, or freeze the region. Copies paste73-values; downloads and XLSX hold the values; undo takes back a run (the74-table it replaced comes back) or the region itself.75-76-The context line says what's under the pointer: on a label, the keys77-that refresh and edit it, and why it failed if it did; on its table,78-which region the cell is part of. A label's end says what it's doing:79-`Running…`, `waiting` for a region it reads, `failed`, `stopped`,80-`not run`, or `no rows`.81-82-**Data > Shell regions** acts on the region under the pointer:83-84-| Command | Key | Does |85-|---|---|---|86-| Refresh region | Enter on its label | Runs its command again, then every region that reads it |87-| Run all regions | F9 | Runs every region, each after the regions it reads |88-| Edit region's command | F2 on its label | Opens its command at the prompt, to change it and run it again |89-| Freeze region | | Turns its table into plain values you can edit, and stops running its command |90-| Delete region | | Removes the region, its command and its table |91-| Stop shell command | Esc | Stops the command running, and those waiting after it |92-93-## Tables between regions49+The head says how many runs came before this one (`[2]`, `[*]` while it50+runs, `[ ]` before it has), the cell's name, and at the right how its run51+stands: `running`, `waiting` for the cell before it, `✓` or `failed` with52+how long it took, `stale`, `not run`, or `saved` for an output read from53+the file. A source is shown whole: a line too long for the screen wraps54+before a pipe where it can, its next rows indented.9455 95-`$r1` in a command is region r1's table, and `$in` is the range96-selected when the prompt was opened, on a sheet that isn't the notebook,97-read again each time the region runs:56+Outputs are drawn by what they are, with values formatted as cells57+([Types](types.md)):9858 99-```nu100-big = $r1 | where size > 1kb | sort-by size --reverse101-$in | group-by region --to-table59+| Output | Shows |60+|---|---|61+| A table (a list of records) | Its columns fitted to their values, numbers right-aligned, its first 10 rows and how many more there are |62+| A record | Its fields, one a line: `key value` |63+| A list | Its items, numbered from 0, as nushell numbers them |64+| Text | Its lines, wrapped |65+| A value | As a cell shows it: `4.2 kB`, `9/27/2026 11:27:31` |66+| An error | `×` and nushell's message, then its help line |67+68+`o` shows a long output whole, and again its first rows. **Enter** on an69+output opens it full-screen: arrows (or `h` `j` `k` `l`) move, `s` sorts70+by the pointer's column and `S` in descending order (again for the71+output's own order), `/` keeps the rows holding what's typed, and Esc72+goes back. The output itself doesn't change.73+74+Note cells are Markdown: headings, **bold**, *italic*, `code`, links (the75+terminal opens them), lists and quotes.76+77+## Keys78+79+Like Jupyter, a notebook has two modes. In command mode (the mode80+indicator says `NOTEBOOK`) keys act on cells; in edit mode (`EDIT`) they81+type into the selected cell.82+83+```mermaid84+stateDiagram-v285+ direction LR86+ [*] --> Command87+ Command --> Edit: Enter, !88+ Edit --> Command: Esc89+ Edit --> Command: Shift+Enter or Ctrl+Enter runs90+ Command --> Output: Enter on an output91+ Output --> Command: Esc10292 ```10393 104-Both reach nu as NUON in a file it reads, never as text spliced into105-the command: `$r1` is a nushell variable holding a table, and `$in` is106-the pipeline's input, as nushell's own107-[`$in`](https://www.nushell.sh/book/pipelines.html#pipeline-input-and-the-special-in-variable)108-is.94+| Key | In command mode |95+|---|---|96+| Up, Down, `j`, `k` | Move between cells, stopping at each output |97+| Home, End, PgUp, PgDn | The first cell, the last, a screen up or down |98+| Enter | Edit the cell; on an output, open it full-screen |99+| Shift+Enter | Run the cell and select the next, adding one at the end |100+| Ctrl+Enter | Run the cell, staying on it |101+| Alt+Enter | Run the cell and add a code cell under it |102+| F9 | Run every cell |103+| `a`, `b` | Add a code cell above, below |104+| `!` | Add a code cell below and edit it |105+| `dd` | Delete the cell |106+| `z` | Undo, bringing back a deleted cell (as Ctrl+Z) |107+| `m`, `y` | Make the cell a note (Markdown), or code |108+| `c`, `x`, `v` | Copy, cut, paste a cell below |109+| `n` | Name the cell |110+| `o` | Show the output whole, or its first rows |111+| `G` | Send the output to a sheet |112+| `ii` | Stop: kill the cell running, and forget those waiting |113+| `00` | Restart: stop, clear every output, count runs from 1 |114+115+| Key | In edit mode |116+|---|---|117+| Esc | Keep what's typed and go back to command mode |118+| Shift+Enter, Ctrl+Enter, Alt+Enter | Run, as in command mode |119+| Enter | A new line, as indented as the one before |120+| Up, Down, Home, End | Move by the lines on screen, wrapped lines too |121+| Ctrl+A, Ctrl+E | The start, the end of the line |122+| Tab | Complete the word at the caret: a cell's `$name`, `$selection`, a linked file, or one of nu's commands |123+124+Every action is a command, in **Data > Notebook**, the palette and the125+shortcuts (Ctrl+/), and File, Edit and the sheet tabs work as anywhere;126+commands for a sheet's cells are off on a notebook's tab. Changes to127+cells are undo steps, as any edit is.128+129+## Running130+131+Cells run in the background, one at a time, so the screen stays live:132+the one running shows `[*]` and those after it `waiting`. **Data >133+Notebook** runs one cell, every cell (F9), the cells above the selected134+one or it and those below; each runs after the cells it reads. A cell135+that fails stops the rest.109136 110-A region reading another depends on it. Refreshing a region runs it111-again and then every region that reads it, directly or through others,112-each after what it reads; a region it reads that hasn't run yet runs113-first. A command reading itself, directly or through others, is114-refused.137+Each cell runs as `nu --no-config-file -c`, so your aliases and custom138+commands aren't there unless `nu-config` is on139+([nushell's configuration](https://www.nushell.sh/book/configuration.html)).140+A cell stops after `nu-timeout` (30 seconds unless set); `ii` stops it141+sooner.115142 116-### Linked files143+## Names and $name117144 118-A [linked file](../files/following.md) is a region too, named after the119-file ([The region](../files/following.md#the-region)), so commands read120-`app.csv` as `$app`. A region reading it doesn't run as rows121-arrive: refreshing it runs its command on the rows the file has now.122-The linked file itself has no command to run.145+A cell that starts `name =` gives its output that name; `n` names a146+cell for you. Later cells read the output as `$name`, a nushell147+variable holding the value, and formulas on any sheet as `nu.name` once148+it's [sent to a sheet](#send-to-a-sheet):123149 124150 ```nu125-errors = $app | where status >= 500 | select time path status ms151+files = ls152+big = $files | where size > 1kb153+$big | get name | str join ", "126154 ```127155 128-[A log file followed live](cookbook.md#a-log-file-followed-live) shows129-it working.130-131-### In formulas156+A name is letters, digits and `_`, not starting with a digit or `__`;157+`in`, `env`, `nu`, `it`, `selection` and `sheet` are taken. Two cells158+can't share a name: the second says so and doesn't run until it's159+renamed.132160 133-Other sheets read a region by name with `nu.` in front, as a named range134-of its table, header included: `=SUM(nu.big)`, `=VLOOKUP("go.mod",135-nu.r1, 3, FALSE)`, `=COUNTIF(nu.app, 503)`. Formulas follow the table as136-it grows, shrinks or moves, and show `#REF!` while it has none.161+A cell reads the sheets two ways, each a table:137162 138-## Running163+| In a cell | Is |164+|---|---|165+| `$selection` | The range selected on the sheet shown last before the notebook, with its first row as the header |166+| `$sheet.A1:C9`, `$sheet.Sales!A1:C9`, `$sheet.'Q1 data'!B2:B40` | That range, of the sheet shown last or the sheet named |167+| `$app` | A [linked file](../files/following.md) named `app`, its rows as they are now |168+169+They reach nu as NUON in a file it reads, never as text spliced into170+the pipeline, so types survive ([Types](types.md)): sizes stay sizes,171+dates stay dates.172+173+### Stale outputs and reactive notebooks174+175+Running a cell again makes the outputs of the cells that read it,176+directly or through others, `stale`: they were made from what it printed177+before. So is a cell's own output once its source is changed.178+179+```mermaid180+flowchart LR181+ run["files runs again"] --> stale["big, and cells reading big: stale"]182+ stale -->|reactive off| you["run them when you want"]183+ stale -->|reactive on| again["they run again, each after what it reads"]184+ you --> fresh["fresh outputs"]185+ again --> fresh186+```139187 140-Commands run in the background, one at a time: the screen stays live,141-and Esc stops the one running and those waiting after it. Each runs as142-`nu --no-config-file -c`, so your aliases and custom commands aren't143-there unless `nu-config` is on144-([nushell's configuration](https://www.nushell.sh/book/configuration.html)).145-A command stops after `nu-timeout` (30 seconds unless set), and keeps at146-most `max-cells` cells, whole rows, saying how many it left out.188+**Data > Notebook > Reactive notebook** (off unless turned on, saved189+with the notebook) runs them again whenever a cell they read runs.190+191+## Send to a sheet192+193+`G` sends the selected cell's output to a sheet: a new sheet named after194+the cell, or a cell of a sheet you pick. There it's a region named after195+the cell, italic as a linked file's rows are, that formulas read as196+`nu.name`, header row included (`=SUM(nu.big)`, `=VLOOKUP("go.mod",197+nu.files, 3, FALSE)`), and charts and pivot tables use. A cell without a198+name is given one first.199+200+```mermaid201+sequenceDiagram202+ participant C as Cell big203+ participant R as Region big on a sheet204+ participant F as =SUM(nu.big)205+ C->>R: G sends the output's rows206+ R->>F: recalculates207+ C->>C: runs again208+ C->>R: the new rows replace the old209+ R->>F: recalculates210+```147211 148-What a command prints is read as a table: a record is one row, a list149-of values that aren't records one column named `value`, and a single150-value that column with one row. When a command fails, its label says151-so and the context line gives nushell's message.212+Like an [array's spill](../formulas/arrays.md#spilled-cells), its cells213+can't be typed over: **Data > Notebook > Freeze output** turns them into214+plain values, and **Remove output** takes them off the sheet. Undo takes215+back sending it, and the rows come back from the cell's output whenever216+undo brings the region back.152217 153218 ## Saving and trust154219 155-The file keeps each region's command, name, place and what it reads,156-not its table ([format](../files/format.md#regions)), and the lines157-typed at the prompt. Opening a notebook never runs anything: its158-regions say `not run`, and F9 runs them all, each after what it reads.220+The file keeps the cells and their outputs as NUON221+([format](../files/format.md#notebooks)), so opening it shows every222+output without running anything; the heads say `saved`. An output larger223+than `nu-save-cell-kb` (1 MB), or past `nu-save-notebook-kb` (8 MB) for224+all of them, is left out: the cell shows `not saved; run to see`, and225+saving says which.159226 160-Like [macros](../sheets/macros.md#macros-from-other-computers), a161-file's commands run as you, with your files, so a notebook saved on162-another computer asks once before they run:227+Opening a file never runs its cells. Like228+[macros](../sheets/macros.md#macros-from-other-computers), a file's cells229+run as you, with your files, so a notebook saved on another computer230+asks once before its cells run:163231 164232 ```165-Run this file's shell commands? Enter Run Esc Cancel233+Run this file's notebook cells? Enter Run Esc Cancel166234 ```167235 168-What you type at the prompt runs without asking. The options, in169-[Configuration](../reference/config.md#nushell-notebooks):236+Cells you write in a notebook made here run without asking. The options,237+in [Configuration](../reference/config.md#nushell-notebooks):170238 171239 | Option | Default | Does |172240 |---|---|---|173-| `shell` | `ask` | `ask` as above; `on` never asks; `off` runs nothing |174-| `nu-timeout` | `30s` | Stops a command that runs longer; `0` lets it run until Esc |175-| `nu-config` | `false` | Runs commands with your `config.nu` and `env.nu` |176-177-[012 serve](../terminal/ssh.md#notebooks) shows notebooks but runs no178-commands unless the server's `serve-shell` is on.241+| `shell` | `ask` | `ask` as above; `on` never asks; `off` runs no cells |242+| `nu-timeout` | `30s` | Stops a cell that runs longer; `0` lets it run until `ii` |243+| `nu-config` | `false` | Runs cells with your `config.nu` and `env.nu` |244+| `nu-save-cell-kb`, `nu-save-notebook-kb` | `1024`, `8192` | How much of the outputs a file keeps |245+246+[012 serve](../terminal/ssh.md#notebooks) shows notebooks and their247+saved outputs, but runs no cells unless the server's `serve-shell` is on.248+249+### Notebook sheets250+251+A file with the notebook sheets of earlier versions of 012, whose252+pipelines were typed at a prompt on the formula bar, opens with each of253+those pipelines as a code cell of the workbook's notebook, named as the254+region was. Their tables stay where they were on the sheet, as the255+cells' outputs sent there, so formulas reading `nu.r1` keep working once256+the cells run; a note on opening says which sheets were converted.