1---2title: "Following files"3sidebar_position: 54---56# Following files78A file can be linked rather than imported: its table shows in a linked9region of a sheet that follows the file, as `tail -f` follows a log. Rows10appended to a CSV, TSV, JSON lines or NUON file come in as they're11written; any file 012 imports (XLSX, SQLite, Parquet too) is read again12when it's rewritten. Formulas, charts, pivot tables and rules over the13region recalculate as rows arrive.1415## Linking a file1617- **Data > Linked file > Link a table** links a file at the active cell,18 which must be empty. The picker lists the files around, as File >19 Import's does, or takes a path.20- **File > Import**, then **Follow the file** among the import locations,21 follows the file in a new sheet after the one shown, named after the22 file. On a new, empty spreadsheet File > Import opens the file instead,23 as it always does; link it with Data > Linked file there.2425A linked file's rows are cells, up to `max-cells`. A Parquet file or a26SQLite table too big for that links as a [source](sources.md) instead,27read in place a page at a time.2829For a SQLite database with several tables, a picker asks which one. Then30a question on the context line asks how many rows to keep:3132| Key | Keeps |33|---|---|34| Enter | Every row, up to `max-cells` ([Configuration](../reference/config.md#max-cells)); past it, the rows that don't fit are left out and the context line says so |35| L | The last rows, as many as typed (1,000 to start with): older rows drop as new ones arrive. The first row, the file's header, stays |3637## The region3839The first row of the region is the file's first row (a NUON or JSON40file's column names, as an import names them); the rows under it are the41file's rows, typed as an import types them. The region is the file's:4243- its cells are read-only; typing into one, pasting over it or clearing44 it says so. Formatting them (bold, number formats, colors) is fine and45 stays on the cell as rows go by;46- its values show in italics, as an array's spilled values do, and47 copying them copies values;48- it grows to the right and down as the file does. Where it would write49 over a cell holding something, its rows aren't shown, and its first50 cell (`#REF!`) and the context line say which cell is in the way;51 clearing that cell reads the file again. An [array](../formulas/arrays.md)'s52 cells, blank ones too, are in its way, and an array that needs its53 cells takes them, whichever came first, as when the file opens.54 Another region's first cell is in its way too, and when two regions'55 tables need the same cells, the one whose first cell comes first, row56 by row, shows and the other shows `#REF!`, whichever grew first;57- inserting or deleting rows or columns before it moves it, and it reads58 the file again there; deleting its first cell's row or column unlinks59 it.6061A linked file is a region, as a [notebook](../nushell/notebooks.md)62cell's output sent to a sheet is, named after the file (`app` for63`app.csv`, `app_2` for a second link to it): formulas on any sheet read64its table as `nu.app`, and notebook cells as `$app`, its rows as they65are when the cell runs ([Names and66$name](../nushell/notebooks.md#names-and-name)).6768The sheet's tab carries a mark, and the context line says what the69region under the pointer is doing:7071| Mark | Context line |72|---|---|73| `●` | `● Following app.csv 1,204 rows, updated 09:14:17`; with a window, `(the last 1,000)` and how many older rows dropped |74| `‖` | `‖ Paused app.csv ...`: Data > Linked file > Follow is off |75| `!` | `! app.csv: the file isn't there`, or why the file can't be read or its rows written. A region with nothing to show has `#REF!` in its first cell |7677## How a file is followed7879012 checks each linked file four times a second with the operating80system's file information alone (size, modification time, identity), so81a file that doesn't change costs one check.8283- **Text tables that grow** (CSV, TSV, `.json`, `.ndjson`, `.jsonl`,84 NUON): the bytes appended since the last check are read and their rows85 added. A line still being written (or a NUON value, or a quoted CSV86 field spanning lines) waits until it's whole. A file shorter than what87 was read (truncated), another file at the same path (rotated, as88 `logrotate` does), or one whose last bytes read differ (rewritten in89 place) is read again from its start. A large file comes in a megabyte at a time, the screen90 staying live between.91- **Files that are rewritten** (XLSX, SQLite, Parquet, and `.wk1`): the92 file is read again whole when its size or modification time changes,93 once they've held still for 0.3 s, so a file being written isn't read94 half done. An XLSX file's sheet shown when it was saved is the one read.9596Rows arrive outside the undo history, as an array's spilled values do:97undo takes back edits, not the file's rows, and rows arriving don't mark98the spreadsheet modified. The first rows a region shows widen its99columns to their text, up to 30 characters, where no width was set, as100a [pivot table](../sheets/pivots.md)'s results do. The widening comes101with the rows rather than an edit, so it stays when undo takes the102region back; set the width to change it.103104## Pause, read again, unlink105106A linked region follows its file, is paused, or shows why it can't read107it, and is read again whole whenever its cells may no longer be the108file's:109110```mermaid111stateDiagram-v2112 state "Read whole" as whole113 state "● Following" as following114 state "‖ Paused" as paused115 state "! Failing" as failing116 [*] --> whole: linked, or the spreadsheet opened117 whole --> following118 following --> following: rows appended119 following --> whole: the file truncated, rotated or rewritten120 following --> whole: Read again, Rows to keep, the region moved121 following --> paused: Follow off122 paused --> following: Follow on, catching up123 following --> failing: the file gone or unreadable124 failing --> whole: the file readable again125 following --> [*]: Unlink, the rows kept as cells126```127128Data > Linked file acts on the region under the pointer, or the sheet's129only one:130131| Command | Does |132|---|---|133| Follow | Pauses following (the region keeps its rows) or follows again, catching up |134| Read again | Reads the file again, whole |135| Rows to keep | Asks again how many rows to keep; the file is read again |136| Unlink | Keeps the rows as ordinary cells, values with their formats, and stops following; undo links the file again |137138## Saving and opening139140A spreadsheet keeps what each region reads, never its rows (see141[The .012 format](format.md#regions)): the file's path relative to142the spreadsheet's folder (absolute when the file is elsewhere and was143linked by an absolute path), its format, the SQLite table or query, and144how many rows to keep. Saving in another folder keeps the paths naming145the same files. Opening the spreadsheet reads the files again and follows146them; a file that isn't there shows in its region, and is read once it147is.148149Under `012 serve`, linked files resolve inside the served folder, as150every file name a session types does ([Serving over SSH](../terminal/ssh.md));151a spreadsheet linking a file outside it shows why in the region.152153## Files from elsewhere154155Following reads files, so a spreadsheet made on another computer asks156once before following files outside its own folder (an absolute path,157or one through `..`): the context line names them, Enter follows them158and records this computer as trusted in the spreadsheet, Esc leaves159their regions empty. Files in the spreadsheet's folder or below never160ask. The trust is the spreadsheet's one trust (`macroOrigin`, saved with161it), which its macros and shell commands need too162([Macros](../sheets/macros.md#macros-from-other-computers)): a163spreadsheet made or trusted on this computer follows its files, runs its164macros and its commands without asking.165166What following costs, measured, is in167[Bounds of support](../contributing/limits.md#following-files).