Skip to content

Scanning Options

Scope: the options that change what the scan counts — staying on one filesystem, excluding by pattern and by cache tag, symlinks followed and not, read-only and extended modes — and why every total in this guide is meaningless without knowing which of them were on.

A scan is a set of decisions made before the first number appears. Two people scan the same disk with different options and get different "truths". These are the decisions that matter.

Staying on one filesystem: -x

A disk is usually several filesystems mounted into one tree: the root filesystem, a separate /home, a tmpfs on /tmp, removable drives. Scanning / crosses all of them, and the totals then answer a question nobody asked. -x limits the scan to the filesystem the starting point lives on; directories on other filesystems are listed but not entered.

Verified with a two-filesystem fixture: a directory holding a local 1 MiB file and a tmpfs mounted over its mounted/ folder with a 2 MiB file inside (devices 86 and 107, for readers counting). Without -x both files count. With -x:

ncdu 1.19 ~ Use the arrow keys to navigate, press ? for help
--- /home/.../fstest2 --------------------------------
    1.0 MiB [##############] /local
>   0.0   B [              ] /mounted

The > flag (chapter 2's table) marks mounted as "on another filesystem" and its 2 MiB simply is not in the scan. On a real system, ncdu -x / is the standard way to ask "what is eating the root filesystem" without /home, /tmp and the USB drive voting. Its cousin --exclude-kernfs skips the Linux pseudo-filesystems (/proc, /sys and friends, flagged ^); on a whole-system scan you generally want both. Named from the help text; the lab has no pseudo- filesystem to practise on.

Excluding by pattern: --exclude

--exclude 'PATTERN' drops every entry whose name (basename only, not the path) matches a shell-style pattern, at any depth:

Check: on the lab, --exclude '*.bin' removed exactly 25,165,824 bytes from the export — installer-a (12,582,912), installer-b (8,388,608) and the cache's blob.bin (4,194,304), that last one two levels down, proving depth does not matter:

$ ncdu -0 --exclude '*.bin' -o - homedir | (sum the dsize fields)
50188288          (unfiltered: 75354112; difference: 25165824)

Excluded entries are excluded from the statistics, not from existence. Inside the browser they still show — flagged <, sized 0.0 B — and the e key hides or reveals them. Here is the cache's app-a under --exclude 'chunk-*': all twenty chunks listed, every one counted as nothing:

--- /home/.../homedir/.cache/app-a -------------------
                             /..
<   0.0   B [              ]  chunk-20.tmp
<   0.0   B [              ]  chunk-19.tmp
<   0.0   B [              ]  chunk-18.tmp
      (…seventeen more, all < and 0.0 B)

Press e and the listing empties to just /... This is a feature, not clutter: an excluded thing you can see is a decision you can audit; an excluded thing that vanishes is next month's mystery total. (The item counts still count them — .cache reported 24 items with its chunks excluded, because they exist. Sizes and counts answer different questions.)

Longer pattern lists live in a file: -X FILE / --exclude-from reads one pattern per line. Same matching, from the help text; the single-pattern form above is the one the captures exercise.

Excluding caches wholesale: --exclude-caches

Caches are the one pile of disk nearly everyone agrees is disposable, and they mark themselves: a directory containing a CACHEDIR.TAG file whose first line is the fixed signature Signature: 8a477f597d28d172789f06886806bc55 is declaring "everything here is a cache, safe to throw away" (a real convention, used by browsers, build tools and backup programs — tar and restic honour it too).

ncdu honours it with --exclude-caches: the contents of any tagged directory are skipped. The lab's .cache is tagged: in the export the directory appears with no children at all, and the entry count for the whole tree falls from 59 to 35 — the twenty chunks, the blob, the tag and the two app directories (24 entries) all leave the statistics. What remains answers "how big is this home directory without the parts I am allowed to delete blind?" — often the only number a cleanup actually needs.

By default ncdu never follows symlinks. A link is measured as itself: its apparent size is the length of its target path (19 and 6 bytes for the lab's two), its disk usage the block it sits in (4096 here), and the target's contents are counted only where the target itself lives. The @ flag marks them.

-L softens this less than you might expect — verified in both versions by export. With -L:

  • link-to-notes (a link to a file) reports the target's apparent size, 25 bytes, and loses its not-a-file flag: the link is measured as the file.
  • link-to-videos (a link to a directory) is still not descended into. The videos are counted once, under Videos/, exactly as before.

So ncdu has no mode in which a directory link duplicates a tree into the totals. That conservatism is deliberate: following directory links can loop forever and double-count everything, and a disk-usage tool that double-counts is worse than one that refuses. If you need a target's tree measured, scan the target.

Read-only: -r

-r starts the browser with its hands tied: pressing d gets a message, not a dialog:

┌───Message────────────────────────────────────────┐
│  Deletion feature disabled.                      │
│                         Press any key to continue│
└──────────────────────────────────────────────────┘

The b shell is disabled too. Use it when browsing a disk you do not trust yourself with — a production server, someone else's home directory, your own at 2 a.m. Deleting also switches itself off in one other place: an imported export (chapter 6) cannot delete at all, because the numbers on screen may describe a tree that is not even on this machine.

2.x spells read-only -rr for "fully" read-only and adds --enable-delete, --enable-shell and --enable-refresh to switch features back on individually; the defaults above are what the captures show, and the toggles' interplay is noted in criteria.md as documentation-level.

Extended info: -e

-e loads the extra metadata chapter 2 kept meeting: modification times (the m column and M sort), and the fuller info popup. It costs a little scan time and a little memory per file — nothing on a home directory, worth knowing on a tree with tens of millions of entries, where ncdu holds the whole scan in RAM. (2.x can browse exports too large for memory in its binary format; chapter 6.)

The remaining startup switches are about presentation and plumbing, and are stated from the --help of the two builds: -q slows screen updates (for slow terminals and SSH), -0/-1/-2 choose no interface / progress-only / full interface (-0 is what makes the exports in chapter 6 scriptable), --color settles the colour question from chapter 2, and 2.x adds -t THREADS for parallel scanning and a config file (--ignore-config bypasses it).

Check: run the lab both ways and compare footers — ncdu homedir against ncdu --exclude-caches homedir. Same tree, same tool, totals 68.9 MiB and (4.1 MiB of cache gone) about 64.8 MiB. Neither run is the truth; each is the answer to the question its options asked.