Reading the Screen
Scope: the browser's anatomy — title, rows, flags, footer — every navigation and display key, sorting, the info popup, the built-in help, and refreshing a snapshot that has gone stale.
Anatomy
After the scan, ncdu shows one directory at a time. The lab's top level again, from the 1.19 capture:
ncdu 1.19 ~ Use the arrow keys to navigate, press ? for help
--- /home/.../homedir --------------------------------
34.0 MiB [##############] /Videos
25.0 MiB [########## ] /Downloads
5.8 MiB [## ] /Pictures
4.1 MiB [# ] /.cache
12.0 KiB [ ] /Documents
4.0 KiB [ ] /deep
@ 4.0 KiB [ ] link-to-notes
@ 4.0 KiB [ ] link-to-videos
4.0 KiB [ ] tiny.txt
0.0 B [ ] /vm-images
e 0.0 B [ ] /empty-dir
Total disk usage: 68.9 MiB Apparent size: 168.8 MiB Items: 58
Top to bottom: the title bar (version,
and the one instruction you need — press
? for help); the path line, naming
the directory you are inside; one row
per entry — an optional one-letter
flag, the size, a bar graph
of that entry's share of the directory,
and the name, with a leading / for
directories; and the footer: total
disk usage, total apparent size, and the
item count (58 — everything below the top
directory; the top itself is not counted).
Directories always show the total of
everything beneath them, files their own
size. That is the entire instrument.
Sizes use binary units by default — MiB
means 1024×1024 bytes — rounded to one
decimal. --si switches to decimal MB;
the same Videos directory reads 34.0 MiB
one way and 35.7 MB the other:
$ ncdu --si homedir
35.7 MB [##############] /Videos
26.2 MB [########## ] /Downloads
6.0 MB [## ] /Pictures
Neither is wrong; they are different rulers. This guide quotes MiB, as ncdu shows them by default.
Moving
The arrow keys move; so do the vi keys
(k up, j down, h back). Enter or
→ opens the selected directory, ←
or h goes back up. Inside a directory
the first row is always /.. — the way
back up, listed as an entry:
--- /home/.../homedir/Videos -------------------------
/..
24.0 MiB [##############] birthday party.mp4
10.0 MiB [##### ] screen-recording.mkv
One quirk worth knowing before it wastes
your time: on entering a directory, the
cursor starts on that /.. row. Pressing
Enter again immediately takes you straight
back out. One j or ↓ first, then Enter,
to descend further. (Verified behaviour,
both versions — the captures in
ncdu-lab/ show the cursor's position.)
q quits. If quitting by accident worries
you, --confirm-quit makes ncdu ask first.
Sorting
Three sort keys, each a toggle — press again to reverse:
n— by name. Files and directories mix alphabetically (.cachefirst here,vm-imageslast);tchanges that to directories-before-files.s— by size, the default, biggest first.C— by item count, when you are hunting the directory with ten thousand small files rather than one big one.
Check: n on the lab's top level gives the
alphabetical screen:
4.1 MiB [# ] /.cache
12.0 KiB [ ] /Documents
25.0 MiB [########## ] /Downloads
5.8 MiB [## ] /Pictures
34.0 MiB [##############] /Videos
4.0 KiB [ ] /deep
e 0.0 B [ ] /empty-dir
@ 4.0 KiB [ ] link-to-notes
@ 4.0 KiB [ ] link-to-videos
4.0 KiB [ ] tiny.txt
0.0 B [ ] /vm-images
With -e at startup (chapter 4) there is
a fourth: M, sort by latest modification
time, and m toggles an mtime column.
Display toggles
a— swap the whole listing between disk usage and apparent size. On the lab this is dramatic: the sparsevm-imagesleaps from last place at 0.0 B to the top at 100.0 MiB, and the symlinks shrink to their true lengths (19 B and 6 B — the length of the target path text):
100.0 MiB [##############] /vm-images
34.0 MiB [#### ] /Videos
25.0 MiB [### ] /Downloads
5.8 MiB [ ] /Pictures
4.1 MiB [ ] /.cache
3.2 KiB [ ] /Documents
2.0 KiB [ ] /deep
@ 19.0 B [ ] link-to-notes
@ 6.0 B [ ] link-to-videos
1.0 B [ ] tiny.txt
e 0.0 B [ ] /empty-dir
c— show item counts per directory (Videos 2, Downloads 4, Pictures 7,.cache24, Documents 4, deep 5 — the cache's twenty chunks announce themselves here before you ever open it).g— cycle the graph column: bar → percentage → both → neither. Percentage view on the lab: Videos 49.4%, Downloads 36.3%, Pictures 8.3%,.cache5.9%.
The flags
A letter before a row is ncdu telling you
the row is not ordinary. The list below is
ncdu's own, from the help screen's Format
tab (press ?, then 2), confirmed
against the lab:
| Flag | Meaning | In the lab |
|---|---|---|
! |
An error occurred reading this directory | chapter 9's locked room |
. |
An error occurred reading a subdirectory | — |
< |
Excluded from the statistics | chapter 4's chunks |
e |
Empty directory | empty-dir/ |
> |
Directory was on another filesystem | chapter 4's mount |
@ |
Not a file or directory (symlink, socket, …) | both links |
^ |
Excluded Linux pseudo-filesystem | scans of / |
H |
Same file already counted (hard link) | chapter 3's photo |
F |
Excluded firmlink (macOS) | — |
Flags are not decoration. ! means the
totals above it are incomplete and ncdu
is the only thing that will tell you so;
chapter 9 returns to that.
The info popup
i opens an info window for the selected
item. Without -e it shows the essentials —
name, path, type, and both sizes with exact
byte counts:
┌───Item info────────────────────1:Info───2:Links─┐
│ Name: img-002.jpg │
│ Path: /home/.../homedir/Pictures/holiday │
│ Type: File │
│ Disk usage: 3.0 MiB (3.145.728 B) │
│ Apparent size: 3.0 MiB (3.145.728 B) │
│ Press i to hide this window │
└─────────────────────────────────────────────────┘
(The byte counts print with . as the
thousands separator in the 1.19 build
tested; 2.9 prints 3,145,728. Same
number, different locale weather.)
With -e, the popup trades Type for Mode,
owner IDs and modification time — and 2.9
adds a line 1.19 does not have: Link
count and Inode, the two facts that
prove a hardlink pair is one file. Both
versions give the popup a second tab:
press 2 and the Links tab lists the
other names of the selected file:
│ /home/.../Pictures/holiday/img-002-copy.jpg │
That tab is the fastest hardlink detector
on the system: select a file, press i,
press 2, and either a partner path is
listed or there is none.
The help screen and the shell
? opens built-in help in three tabs —
1:Keys, 2:Format, 3:About —
scroll with the arrow keys, switch with
the number keys, close with q. Every key
in this chapter is listed there; the help
is part of the program, identical in
spirit across versions, and worth the
thirty seconds it takes to read once.
b spawns a shell in the directory you
are browsing — handy for acting on what
you found without retyping the path (exit
returns you to the browser). Verified in
both versions. The read-only flag -r
turns the shell off along with deleting —
chapter 4 covers -r, chapter 5 explains
why you might browse a strange disk with
it on.
One decoration note: whether the browser
uses colour depends on the version —
1.19 colours by default, 2.9 does not
(the upstream project turned the default
off again for legibility); --color dark
or --color off settles it explicitly.
The transcripts in ncdu-lab/ are plain
text, so the chapters quote the screens
without colour either way.
A snapshot, not a monitor
The browser shows the scan, not the disk.
If files change while you browse, the
numbers do not move — until you press r,
which rescans the directory you are in.
Verified on the lab: a 7 MiB file added to
Downloads from another terminal was
invisible, then appeared in place after
r:
12.0 MiB [##############] installer-a.bin
8.0 MiB [######### ] installer-b.bin
7.0 MiB [######## ] late-addition.bin ← after r
5.0 MiB [##### ] forgotten.zip
4.0 KiB [ ] readme.txt
Remember this when a total looks wrong in chapter 9: the first question is always "how old is this scan?"