du

Overview ¶

Package du implements the du builtin command.

du — estimate file space usage

Usage: du [OPTION]... [FILE]...

Summarize device usage of the set of FILEs, recursively for directories. With no FILE, du operates on the current directory.

Output format: "<size>\t<path>\n" per entry. Sizes are reported in 1024-byte blocks by default (this shell does not honour POSIXLY_CORRECT).

Accepted flags:

-a, --all
    Write counts for all files, not just directories.

-s, --summarize
    Display only a per-argument total. Mutually exclusive with -a
    and with --max-depth.

-c, --total
    Produce a grand total row.

-d, --max-depth=N
    Print the total for a directory (or file, with --all) only if it
    is N or fewer levels below the command-line argument.
    --max-depth=0 is equivalent to --summarize.

-S, --separate-dirs
    For directories, do not include size of subdirectories.

-L, --dereference
    Follow all symbolic links during traversal. Cycles are detected
    via dev+inode identity and reported as errors.

-P, --no-dereference
    Never follow symbolic links (this is the default).

-0, --null
    End each output line with NUL, not newline.

-h, --human-readable
    Print sizes in human-readable format using 1024-power units
    (e.g. 1.0K, 234M, 2.0G).

--si
    Like -h, but use powers of 1000.

-k
    Use 1024-byte blocks (this is already the default).

-m
    Use 1 MiB (1024*1024) blocks.

-b, --bytes
    Equivalent to --apparent-size --block-size=1: report apparent
    size in bytes.

--apparent-size
    Print apparent sizes (file size in bytes) rather than allocated
    disk usage. Apparent sizes ignore sparse-file holes, internal
    fragmentation, and indirect blocks.

--help
    Print this usage message to stdout and exit 0.

Rejected for security or scope:

--files0-from=FILE     Reads filenames from another file; data
                       exfiltration risk in sandboxed environments.
                       Same rationale as wc --files0-from.
--exclude-from=FILE    Reads exclude patterns from a file; same class.
-X, --exclude-from     (alias of --exclude-from)
--exclude=PATTERN      Glob-pattern filter; deferred until a safe
                       glob implementation lands. The shell's
                       glob→regex translator is currently sensitive
                       to certain multi-byte sequences (see fuzz
                       findings) and shipping --exclude before
                       hardening that path would expose pattern-
                       triggered failures to the du surface.

All unknown flags are rejected by pflag with exit code 1, so security-sensitive flags above are simply not registered.

Behaviour notes that intentionally diverge from GNU du:

• When `-P` is in effect (the default), a top-level operand that is itself a symbolic link is reported as the symlink, not its target. GNU follows the operand-level link in this case but our implementation prefers the stricter no-follow-by-default reading. Use `-L` to follow.

Exit codes:

0  All operands processed successfully.
1  At least one error occurred (missing file, permission denied,
   invalid argument, etc.).

Memory and resource bounds:

Directory entries are read via callCtx.OpenDir's streaming
ReadDirFile so memory usage is proportional to traversal depth, not
directory width. Recursion is capped at maxRecursionDepth (256).
Each directory is opened in a per-iteration scope so its file
descriptor closes before recursion descends — depth × 1 FD instead
of depth × N. Hardlink-dedup tracking is bounded at maxDedupEntries
(1<<20) per call to prevent unbounded growth on adversarially
hardlink-rich subtrees; once the cap is hit, further hardlinks are
counted multiple times rather than triggering a memory exhaustion.