mirror of
https://code.blicky.net/yorhel/ncdu.git
synced 2026-01-12 17:08:39 -09:00
Rewrite man page in mdoc
Still not a fan of roff, but even less a fan of build system stuff and a dependency on a tool that is getting less ubiquitous over time. I've removed the "hard links" section from the man page for now. Such a section might be useful, but much of it was outdated.
This commit is contained in:
Yorhel
parent
a2eb84e7d3
commit
491988d9a5
4 changed files with 519 additions and 581 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -3,7 +3,6 @@
|
|||
|
||||
*.swp
|
||||
*~
|
||||
ncdu.1
|
||||
ncurses
|
||||
static-*/
|
||||
zig-cache/
|
||||
|
|
|
|||
16
Makefile
16
Makefile
|
|
@ -14,7 +14,7 @@ ZIG_FLAGS ?= -Doptimize=ReleaseFast
|
|||
NCDU_VERSION=$(shell grep 'program_version = "' src/main.zig | sed -e 's/^.*"\(.\+\)".*$$/\1/')
|
||||
|
||||
.PHONY: build
|
||||
build: release doc
|
||||
build: release
|
||||
|
||||
release:
|
||||
$(ZIG) build ${ZIG_FLAGS}
|
||||
|
|
@ -25,21 +25,13 @@ debug:
|
|||
clean:
|
||||
rm -rf zig-cache zig-out
|
||||
|
||||
distclean: clean
|
||||
rm -f ncdu.1
|
||||
|
||||
doc: ncdu.1
|
||||
|
||||
ncdu.1: ncdu.pod src/main.zig
|
||||
pod2man --center "ncdu manual" --release "ncdu-${NCDU_VERSION}" ncdu.pod >ncdu.1
|
||||
|
||||
install: install-bin install-doc
|
||||
|
||||
install-bin: release
|
||||
mkdir -p ${BINDIR}
|
||||
install -m0755 zig-out/bin/ncdu ${BINDIR}/
|
||||
|
||||
install-doc: doc
|
||||
install-doc:
|
||||
mkdir -p ${MANDIR}
|
||||
install -m0644 ncdu.1 ${MANDIR}/
|
||||
|
||||
|
|
@ -52,10 +44,10 @@ uninstall-bin:
|
|||
uninstall-doc:
|
||||
rm -f ${MANDIR}/ncdu.1
|
||||
|
||||
dist: doc
|
||||
dist:
|
||||
rm -f ncdu-${NCDU_VERSION}.tar.gz
|
||||
mkdir ncdu-${NCDU_VERSION}
|
||||
for f in ncdu.1 `git ls-files | grep -v ^\.gitignore`; do mkdir -p ncdu-${NCDU_VERSION}/`dirname $$f`; ln -s "`pwd`/$$f" ncdu-${NCDU_VERSION}/$$f; done
|
||||
for f in `git ls-files | grep -v ^\.gitignore`; do mkdir -p ncdu-${NCDU_VERSION}/`dirname $$f`; ln -s "`pwd`/$$f" ncdu-${NCDU_VERSION}/$$f; done
|
||||
tar -cophzf ncdu-${NCDU_VERSION}.tar.gz --sort=name ncdu-${NCDU_VERSION}
|
||||
rm -rf ncdu-${NCDU_VERSION}
|
||||
|
||||
|
|
|
|||
515
ncdu.1
Normal file
515
ncdu.1
Normal file
|
|
@ -0,0 +1,515 @@
|
|||
.\" SPDX-FileCopyrightText: Yoran Heling <projects@yorhel.nl>
|
||||
.\" SPDX-License-Identifier: MIT
|
||||
.Dd January 21, 2024
|
||||
.Dt NCDU 1
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm ncdu
|
||||
.Nd NCurses Disk Usage
|
||||
.Sh SYNOPSIS
|
||||
.Nm
|
||||
.Op Fl f Ar file
|
||||
.Op Fl o Ar file
|
||||
.Op Fl e , \-extended , \-no\-extended
|
||||
.Op Fl \-ignore\-config
|
||||
.Op Fl x , \-one\-file\-system , \-cross\-file\-system
|
||||
.Op Fl \-exclude Ar pattern
|
||||
.Op Fl X , \-exclude\-from Ar file
|
||||
.Op Fl \-include\-caches , \-exclude\-caches
|
||||
.Op Fl L , \-follow\-symlinks , \-no\-follow\-symlinks
|
||||
.Op Fl \-include\-kernfs , \-exclude\-kernfs
|
||||
.Op Fl 0 , 1 , 2
|
||||
.Op Fl q , \-slow\-ui\-updates , \-fast\-ui\-updates
|
||||
.Op Fl \-enable\-shell , \-disable\-shell
|
||||
.Op Fl \-enable\-delete , \-disable\-delete
|
||||
.Op Fl \-enable\-refresh , \-disable\-refresh
|
||||
.Op Fl r
|
||||
.Op Fl \-si , \-no\-si
|
||||
.Op Fl \-disk\-usage , \-apparent\-size
|
||||
.Op Fl \-show\-hidden , \-hide\-hidden
|
||||
.Op Fl \-show\-itemcount , \-hide\-itemcount
|
||||
.Op Fl \-show\-mtime , \-hide\-mtime
|
||||
.Op Fl \-show\-graph , \-hide\-graph
|
||||
.Op Fl \-show\-percent , \-hide\-percent
|
||||
.Op Fl \-graph\-style Ar hash | half\-block | eighth\-block
|
||||
.Op Fl \-shared\-column Ar off | shared | unique
|
||||
.Op Fl \-sort Ar column
|
||||
.Op Fl \-enable\-natsort , \-disable\-natsort
|
||||
.Op Fl \-group\-directories\-first , \-no\-group\-directories\-first
|
||||
.Op Fl \-confirm\-quit , \-no\-confirm\-quit
|
||||
.Op Fl \-confirm\-delete , \-no\-confirm\-delete
|
||||
.Op Fl \-color Ar off | dark | dark-bg
|
||||
.Op Ar path
|
||||
.Nm
|
||||
.Op Fl h , \-help
|
||||
.Nm
|
||||
.Op Fl v , V , \-version
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
(NCurses Disk Usage) is an interactive curses-based version of the well-known
|
||||
.Xr du 1 ,
|
||||
and provides a fast way to see what directories are using your disk space.
|
||||
.Sh OPTIONS
|
||||
.Ss Mode Selection
|
||||
.Bl -tag -width Ds
|
||||
.It Fl h , \-help
|
||||
Print a short help message and quit.
|
||||
.It Fl v , V , \-version
|
||||
Print version and quit.
|
||||
.It Fl f Ar file
|
||||
Load the given file, which has earlier been created with the
|
||||
.Fl o
|
||||
flag.
|
||||
If
|
||||
.Ar file
|
||||
is equivalent to '\-', the file is read from standard input.
|
||||
.Pp
|
||||
For the sake of preventing a screw-up, the current version of
|
||||
.Nm
|
||||
will assume that the directory information in the imported file does not
|
||||
represent the filesystem on which the file is being imported.
|
||||
That is, the refresh, file deletion and shell spawning options in the browser
|
||||
will be disabled.
|
||||
.It Ar dir
|
||||
Scan the given directory.
|
||||
.It Fl o Ar file
|
||||
Export all necessary information to
|
||||
.Ar file
|
||||
instead of opening the browser interface.
|
||||
If
|
||||
.Ar file
|
||||
is '\-', the data is written to standard output.
|
||||
See the examples section below for some handy use cases.
|
||||
.Pp
|
||||
Be warned that the exported data may grow quite large when exporting a
|
||||
directory with many files.
|
||||
10.000 files will get you an export in the order of 600 to 700 KiB
|
||||
uncompressed, or a little over 100 KiB when compressed with gzip.
|
||||
This scales linearly, so be prepared to handle a few tens of megabytes when
|
||||
dealing with millions of files.
|
||||
.It Fl e , \-extended , \-no\-extended
|
||||
Enable/disable extended information mode.
|
||||
This will, in addition to the usual file information, also read the ownership,
|
||||
permissions and last modification time for each file.
|
||||
This will result in higher memory usage (by roughly ~30%) and in a larger
|
||||
output file when exporting.
|
||||
.Pp
|
||||
When using the file export/import function, this flag should be added both when
|
||||
exporting (to make sure the information is added to the export) and when
|
||||
importing (to read this extra information in memory).
|
||||
This flag has no effect when importing a file that has been exported without
|
||||
the extended information.
|
||||
.Pp
|
||||
This enables viewing and sorting by the latest child mtime, or modified time,
|
||||
using 'm' and 'M', respectively.
|
||||
.It Fl \-ignore\-config
|
||||
Do not attempt to load any configuration files.
|
||||
.El
|
||||
.Ss Scan Options
|
||||
These options affect the scanning progress, they have no effect when importing
|
||||
directory information from a file.
|
||||
.Bl -tag -width Ds
|
||||
.It Fl x , \-one\-file\-system
|
||||
Do not cross filesystem boundaries, i.e. only count files and directories on
|
||||
the same filesystem as the directory being scanned.
|
||||
.It Fl \-cross\-file\-system
|
||||
Do cross filesystem boundaries.
|
||||
This is the default, but can be specified to overrule a previously configured
|
||||
.Fl x .
|
||||
.It Fl \-exclude Ar pattern
|
||||
Exclude files that match
|
||||
.Ar pattern .
|
||||
The files are still displayed by default, but are not counted towards the disk
|
||||
usage statistics.
|
||||
This argument can be added multiple times to add more patterns.
|
||||
.It Fl X , \-exclude\-from Ar file
|
||||
Exclude files that match any pattern in
|
||||
.Ar file .
|
||||
Patterns should be separated by a newline.
|
||||
.It Fl \-include\-caches , \-exclude\-caches
|
||||
Include (default) or exclude directories containing
|
||||
.Pa CACHEDIR.TAG .
|
||||
Excluded cache directories are still displayed, but their contents will not be
|
||||
scanned or counted towards the disk usage statistics.
|
||||
.Lk https://bford.info/cachedir/
|
||||
.It Fl L , \-follow\-symlinks , \-no\-follow\-symlinks
|
||||
Follow (or not) symlinks and count the size of the file they point to.
|
||||
This option does not follow symlinks to directories and will cause each
|
||||
symlinked file to count as a unique file.
|
||||
This is different from how hard links are handled.
|
||||
The exact counting behavior of this flag is subject to change in the future.
|
||||
.It Fl \-include\-kernfs , \-exclude\-kernfs
|
||||
(Linux only) Include (default) or exclude Linux pseudo filesystems such as
|
||||
.Pa /proc
|
||||
(procfs) and
|
||||
.Pa /sys
|
||||
(sysfs).
|
||||
.Pp
|
||||
The complete list of currently known pseudo filesystems is: binfmt, bpf, cgroup,
|
||||
cgroup2, debug, devpts, proc, pstore, security, selinux, sys, trace.
|
||||
.El
|
||||
.Ss Interface Options
|
||||
.Bl -tag -width Ds
|
||||
.It Fl 0
|
||||
Don't give any feedback while scanning a directory or importing a file, except
|
||||
when a fatal error occurs.
|
||||
Ncurses will not be initialized until the scan is complete.
|
||||
When exporting the data with
|
||||
.Fl o ,
|
||||
ncurses will not be initialized at all.
|
||||
This option is the default when exporting to standard output.
|
||||
.It Fl 1
|
||||
Similar to
|
||||
.Fl 0 ,
|
||||
but does give feedback on the scanning progress with a single line of output.
|
||||
This option is the default when exporting to a file.
|
||||
.Pp
|
||||
In some cases, the ncurses browser interface which you'll see after the
|
||||
scan/import is complete may look garbled when using this option.
|
||||
If you're not exporting to a file,
|
||||
.Fl 2
|
||||
is usually a better choice.
|
||||
.It Fl 2
|
||||
Show a full-screen ncurses interface while scanning a directory or importing
|
||||
a file.
|
||||
This is the only interface that provides feedback on any non-fatal errors while
|
||||
scanning.
|
||||
.It Fl q , \-slow\-ui\-updates , \-fast\-ui\-updates
|
||||
Change the UI update interval while scanning or importing.
|
||||
.Nm
|
||||
updates the screen 10 times a second by default (with
|
||||
.Fl \-fast\-ui\-updates
|
||||
), this can be decreased to once every 2 seconds with
|
||||
.Fl q
|
||||
or
|
||||
.Fl \-slow\-ui\-updates .
|
||||
This option can be used to save bandwidth over remote connections.
|
||||
This option has no effect in combination with
|
||||
.Fl 0 .
|
||||
.It Fl \-enable\-shell , \-disable\-shell
|
||||
Enable or disable shell spawning from the file browser.
|
||||
This feature is enabled by default when scanning a live directory and disabled
|
||||
when importing from file.
|
||||
.It Fl \-enable\-delete , \-disable\-delete
|
||||
Enable or disable the built-in file deletion feature.
|
||||
This feature is enabled by default when scanning a live directory and disabled
|
||||
when importing from file.
|
||||
Explicitly disabling the deletion feature can work as a safeguard to prevent
|
||||
accidental data loss.
|
||||
.It Fl \-enable\-refresh , \-disable\-refresh
|
||||
Enable or disable directory refreshing from the file browser.
|
||||
This feature is enabled by default when scanning a live directory and disabled
|
||||
when importing from file.
|
||||
.It Fl r
|
||||
Read-only mode.
|
||||
When given once, this is an alias for
|
||||
.Fl \-disable\-delete ,
|
||||
when given twice it will also add
|
||||
.Fl \-disable\-shell ,
|
||||
thus ensuring that there is no way to modify the file system from within
|
||||
.Nm .
|
||||
.It Fl \-si , \-no\-si
|
||||
List sizes using base 10 prefixes, that is, powers of 1000 (KB, MB, etc), as
|
||||
defined in the International System of Units (SI), instead of the usual base 2
|
||||
prefixes (KiB, MiB, etc).
|
||||
.It Fl \-disk\-usage , \-apparent\-size
|
||||
Select whether to display disk usage (default) or apparent sizes.
|
||||
Can also be toggled in the file browser with the 'a' key.
|
||||
.It Fl \-show\-hidden , \-hide\-hidden
|
||||
Show (default) or hide "hidden" and excluded files.
|
||||
Can also be toggled in the file browser with the 'e' key.
|
||||
.It Fl \-show\-itemcount , \-hide\-itemcount
|
||||
Show or hide (default) the item counts column.
|
||||
Can also be toggled in the file browser with the 'c' key.
|
||||
.It Fl \-show\-mtime , \-hide\-mtime
|
||||
Show or hide (default) the last modification time column.
|
||||
Can also be toggled in the file browser with the 'm' key.
|
||||
This option is ignored when not in extended mode, see
|
||||
.Fl e .
|
||||
.It Fl \-show\-graph , \-hide\-graph
|
||||
Show (default) or hide the relative size bar column.
|
||||
Can also be toggled in the file browser with the 'g' key.
|
||||
.It Fl \-show\-percent , \-hide\-percent
|
||||
Show (default) or hide the relative size percent column.
|
||||
Can also be toggled in the file browser with the 'g' key.
|
||||
.It Fl \-graph\-style Ar hash | half\-block | eighth\-block
|
||||
Change the way that the relative size bar column is drawn.
|
||||
Recognized values are
|
||||
.Ar hash
|
||||
to draw ASCII '#' characters (default and most portable),
|
||||
.Ar half\-block
|
||||
to use half-block drawing characters or
|
||||
.Ar eighth\-block
|
||||
to use eighth-block drawing characters.
|
||||
Eighth-block characters are the most precise but may not render correctly in
|
||||
all terminals.
|
||||
.It Fl \-shared\-column Ar off | shared | unique
|
||||
Set to
|
||||
.Ar off
|
||||
to disable the shared size column for directories,
|
||||
.Ar shared
|
||||
(default) to display shared directory sizes as a separate column or
|
||||
.Ar unique
|
||||
to display unique directory sizes as a separate column.
|
||||
These options can also be cycled through in the file browser with the 'u' key.
|
||||
.It Fl \-sort Ar column
|
||||
Change the default column to sort on.
|
||||
Accepted values are
|
||||
.Ar disk\-usage
|
||||
(the default),
|
||||
.Ar name , apparent\-size , itemcount
|
||||
or
|
||||
.Ar mtime .
|
||||
The latter only makes sense in extended mode, see
|
||||
.Fl e .
|
||||
.Pp
|
||||
The column name can be suffixed with
|
||||
.Li \-asc
|
||||
or
|
||||
.Li \-desc
|
||||
to change the order to ascending or descending, respectively.
|
||||
For example,
|
||||
.Li \-\-sort=name\-desc
|
||||
to sort by name in descending order.
|
||||
.It Fl \-enable\-natsort , \-disable\-natsort
|
||||
Enable (default) or disable natural sort when sorting by file name.
|
||||
.It Fl \-group\-directories\-first , \-no\-group\-directories\-first
|
||||
Sort (or not) directories before files.
|
||||
.It Fl \-confirm\-quit , \-no\-confirm\-quit
|
||||
Require a confirmation before quitting ncdu.
|
||||
Can be helpful when you accidentally press 'q' during or after a very long scan.
|
||||
.It Fl \-confirm\-delete , \-no\-confirm\-delete
|
||||
Require a confirmation before deleting a file or directory.
|
||||
Enabled by default, but can be disabled if you're absolutely sure you won't
|
||||
accidentally press 'd'.
|
||||
.It Fl \-color Ar off | dark | dark-bg
|
||||
Set the color scheme.
|
||||
The following schemes are recognized:
|
||||
.Ar off
|
||||
to disable colors,
|
||||
.Ar dark
|
||||
for a color scheme intended for dark backgrounds and
|
||||
.Ar dark\-bg
|
||||
for a variation of the
|
||||
.Ar dark
|
||||
color scheme that also works in terminals with a light background.
|
||||
.Pp
|
||||
The default is
|
||||
.Ar dark\-bg
|
||||
unless the
|
||||
.Ev NO_COLOR
|
||||
environment variable is set.
|
||||
.El
|
||||
.Sh CONFIGURATION
|
||||
.Nm
|
||||
can be configured by placing command-line options in
|
||||
.Pa /etc/ncdu.conf
|
||||
or
|
||||
.Pa $HOME/.config/ncdu/config .
|
||||
If both files exist, the system configuration will be loaded before the user
|
||||
configuration, allowing users to override options set in the system
|
||||
configuration.
|
||||
Options given on the command line will override options set in the
|
||||
configuration files.
|
||||
The files will not be read at all when
|
||||
.Fl \-ignore\-config
|
||||
is given on the command line.
|
||||
.Pp
|
||||
The configuration file format is simply one command line option per line.
|
||||
Lines starting with '#' are ignored.
|
||||
Example configuration file:
|
||||
.Bd -literal -offset indent
|
||||
# Always enable extended mode
|
||||
\-e
|
||||
|
||||
# Disable file deletion
|
||||
\-\-disable\-delete
|
||||
|
||||
# Exclude .git directories
|
||||
\-\-exclude .git
|
||||
.Ed
|
||||
.Sh KEYS
|
||||
.Bl -tag -width Ds
|
||||
.It ?
|
||||
Open help + keys + about screen
|
||||
.It up , down , j , k
|
||||
Cycle through the items
|
||||
.It right, enter, l
|
||||
Open selected directory
|
||||
.It left, <, h
|
||||
Go to parent directory
|
||||
.It n
|
||||
Order by filename (press again for descending order)
|
||||
.It s
|
||||
Order by filesize (press again for descending order)
|
||||
.It C
|
||||
Order by number of items (press again for descending order)
|
||||
.It a
|
||||
Toggle between showing disk usage and showing apparent size.
|
||||
.It M
|
||||
Order by latest child mtime, or modified time (press again for descending
|
||||
order).
|
||||
Requires the
|
||||
.Fl e
|
||||
flag.
|
||||
.It d
|
||||
Delete the selected file or directory.
|
||||
An error message will be shown when the contents of the directory do not match
|
||||
or do not exist anymore on the filesystem.
|
||||
.It t
|
||||
Toggle dirs before files when sorting.
|
||||
.It g
|
||||
Toggle between showing percentage, graph, both, or none.
|
||||
Percentage is relative to the size of the current directory, graph is relative
|
||||
to the largest item in the current directory.
|
||||
.It u
|
||||
Toggle display of the shared / unique size column for directories that share
|
||||
hard links.
|
||||
This column is only visible if the current listing contains directories with
|
||||
shared hard links.
|
||||
.It c
|
||||
Toggle display of child item counts.
|
||||
.It m
|
||||
Toggle display of latest child mtime, or modified time.
|
||||
Requires the
|
||||
.Fl e
|
||||
flag.
|
||||
.It e
|
||||
Show/hide 'hidden' or 'excluded' files and directories.
|
||||
Be aware that even if you can't see the hidden files and directories, they are
|
||||
still there and they are still included in the directory sizes.
|
||||
If you suspect that the totals shown at the bottom of the screen are not
|
||||
correct, make sure you haven't enabled this option.
|
||||
.It i
|
||||
Show information about the current selected item.
|
||||
.It r
|
||||
Refresh/recalculate the current directory.
|
||||
.It b
|
||||
Spawn shell in current directory.
|
||||
.Pp
|
||||
.Nm
|
||||
determines your preferred shell from the
|
||||
.Ev NCDU_SHELL
|
||||
or
|
||||
.Ev SHELL
|
||||
environment variable (in that order), or calls
|
||||
.Pa /bin/sh
|
||||
if neither are set.
|
||||
This allows you to also configure another command to be run when he 'b' key is
|
||||
pressed.
|
||||
For example, to spawn the
|
||||
.Xr vifm 1
|
||||
file manager instead of a shell, run
|
||||
.Nm
|
||||
as follows:
|
||||
.Dl NCDU_SHELL=vifm ncdu
|
||||
The
|
||||
.Ev NCDU_LEVEL
|
||||
environment variable is set or incremented before spawning the shell, allowing
|
||||
you to detect if your shell is running from within
|
||||
.Nm .
|
||||
This can be useful to avoid nesting multiple instances, although
|
||||
.Nm
|
||||
itself does not (currently) warn about or prevent this situation.
|
||||
.It q
|
||||
Quit
|
||||
.El
|
||||
.Sh FILE FLAGS
|
||||
Entries in the browser interface may be prefixed by a one\-character flag.
|
||||
These flags have the following meaning:
|
||||
.Bl -tag -width Ds
|
||||
.It !
|
||||
An error occurred while reading this directory.
|
||||
.It \.
|
||||
An error occurred while reading a subdirectory, so the indicated size may not
|
||||
be correct.
|
||||
.It <
|
||||
File or directory is excluded from the statistics by using exclude patterns.
|
||||
.It >
|
||||
Directory is on another filesystem.
|
||||
.It ^
|
||||
Directory is excluded from the statistics due to being a Linux pseudo
|
||||
filesystem.
|
||||
.It @
|
||||
This is neither a file nor a folder (symlink, socket, ...).
|
||||
.It H
|
||||
Same file was already counted (hard link).
|
||||
.It e
|
||||
Empty directory.
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
To scan and browse the directory you're currently in, all you need is a simple:
|
||||
.Dl ncdu
|
||||
If you want to scan a full filesystem, for example your root filesystem, then
|
||||
you'll want to use
|
||||
.Fl x :
|
||||
.Dl ncdu \-x /
|
||||
.Pp
|
||||
Since scanning a large directory may take a while, you can scan a directory and
|
||||
export the results for later viewing:
|
||||
.Bd -literal -offset indent
|
||||
ncdu \-1xo\- / | gzip >export.gz
|
||||
# ...some time later:
|
||||
zcat export.gz | ncdu \-f\-
|
||||
.Ed
|
||||
To export from a cron job, make sure to replace
|
||||
.Fl 1
|
||||
with
|
||||
.Fl 0
|
||||
to suppress any unnecessary output.
|
||||
.Pp
|
||||
You can also export a directory and browse it once scanning is done:
|
||||
.Dl ncdu \-o\- | tee export.file | ./ncdu \-f\-
|
||||
The same is possible with gzip compression, but is a bit kludgey:
|
||||
.Dl ncdu \-o\- | gzip | tee export.gz | gunzip | ./ncdu \-f\-
|
||||
.Pp
|
||||
To scan a system remotely, but browse through the files locally:
|
||||
.Dl ssh \-C user@system ncdu \-o\- / | ./ncdu \-f\-
|
||||
The
|
||||
.Fl C
|
||||
option to ssh enables compression, which will be very useful over slow links.
|
||||
Remote scanning and local viewing has two major advantages when
|
||||
compared to running
|
||||
.Nm
|
||||
directly on the remote system: You can browse through the scanned directory on
|
||||
the local system without any network latency, and
|
||||
.Nm
|
||||
does not keep the entire directory structure in memory when exporting, so this
|
||||
won't consume much memory on the remote system.
|
||||
.Sh BUGS
|
||||
Directory hard links and firmlinks (MacOS) are not supported.
|
||||
They are not detected as being hard links, and will thus get scanned and
|
||||
counted multiple times.
|
||||
.Pp
|
||||
Some minor glitches may appear when displaying filenames that contain multibyte
|
||||
or multicolumn characters.
|
||||
.Pp
|
||||
The unique and shared directory sizes are calculated based on the assumption
|
||||
that the link count of hard links does not change during a filesystem scan or
|
||||
in between refreshes.
|
||||
If this does happen, for example when a hard link is deleted, then these
|
||||
numbers will be very much incorrect and a full refresh by restarting ncdu is
|
||||
needed to get correct numbers again.
|
||||
.Pp
|
||||
All sizes are internally represented as a signed 64bit integer.
|
||||
If you have a directory larger than 8 EiB minus one byte, ncdu will clip its
|
||||
size to 8 EiB minus one byte.
|
||||
When deleting or refreshing items in a directory with a clipped size, the
|
||||
resulting sizes will be incorrect.
|
||||
Likewise, item counts are stored in a 32-bit integer, so will be incorrect in
|
||||
the unlikely event that you happen to have more than 4 billion items in a
|
||||
directory.
|
||||
.Pp
|
||||
Please report any other bugs you may find at the bug tracker, which can be
|
||||
found on the web site at
|
||||
.Lk https://dev.yorhel.nl/ncdu
|
||||
.Sh SEE ALSO
|
||||
.Xr du 1 ,
|
||||
.Xr tree 1 .
|
||||
.Pp
|
||||
.Nm
|
||||
has a website:
|
||||
.Lk https://dev.yorhel.nl/ncdu
|
||||
.Sh AUTHORS
|
||||
Written by
|
||||
.An Yorhel Aq Mt projects@yorhel.nl
|
||||
568
ncdu.pod
568
ncdu.pod
|
|
@ -1,568 +0,0 @@
|
|||
SPDX-FileCopyrightText: 2021-2023 Yoran Heling <projects@yorhel.nl>
|
||||
SPDX-License-Identifier: MIT
|
||||
|
||||
=head1 NAME
|
||||
|
||||
B<ncdu> - NCurses Disk Usage
|
||||
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<ncdu> [I<options>] I<dir>
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
ncdu (NCurses Disk Usage) is a curses-based version of the well-known 'du', and
|
||||
provides a fast way to see what directories are using your disk space.
|
||||
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=head2 Mode Selection
|
||||
|
||||
=over
|
||||
|
||||
=item B<-h>, B<--help>
|
||||
|
||||
Print a short help message and quit.
|
||||
|
||||
=item B<-v>, B<-V>, B<--version>
|
||||
|
||||
Print ncdu version and quit.
|
||||
|
||||
=item B<-f> I<FILE>
|
||||
|
||||
Load the given file, which has earlier been created with the C<-o> option. If
|
||||
I<FILE> is equivalent to C<->, the file is read from standard input.
|
||||
|
||||
For the sake of preventing a screw-up, the current version of ncdu will assume
|
||||
that the directory information in the imported file does not represent the
|
||||
filesystem on which the file is being imported. That is, the refresh, file
|
||||
deletion and shell spawning options in the browser will be disabled.
|
||||
|
||||
=item I<dir>
|
||||
|
||||
Scan the given directory.
|
||||
|
||||
=item B<-o> I<FILE>
|
||||
|
||||
Export all necessary information to I<FILE> instead of opening the browser
|
||||
interface. If I<FILE> is C<->, the data is written to standard output. See the
|
||||
examples section below for some handy use cases.
|
||||
|
||||
Be warned that the exported data may grow quite large when exporting a
|
||||
directory with many files. 10.000 files will get you an export in the order of
|
||||
600 to 700 KiB uncompressed, or a little over 100 KiB when compressed with
|
||||
gzip. This scales linearly, so be prepared to handle a few tens of megabytes
|
||||
when dealing with millions of files.
|
||||
|
||||
=item B<-e>, B<--extended>, B<--no-extended>
|
||||
|
||||
Enable/disable extended information mode. This will, in addition to the usual
|
||||
file information, also read the ownership, permissions and last modification
|
||||
time for each file. This will result in higher memory usage (by roughly ~30%)
|
||||
and in a larger output file when exporting.
|
||||
|
||||
When using the file export/import function, this flag will need to be added
|
||||
both when exporting (to make sure the information is added to the export), and
|
||||
when importing (to read this extra information in memory). This flag has no
|
||||
effect when importing a file that has been exported without the extended
|
||||
information.
|
||||
|
||||
This enables viewing and sorting by the latest child mtime, or modified time,
|
||||
using 'm' and 'M', respectively.
|
||||
|
||||
=item B<--ignore-config>
|
||||
|
||||
Do not attempt to load any configuration files.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Scan Options
|
||||
|
||||
These options affect the scanning progress, and have no effect when importing
|
||||
directory information from a file.
|
||||
|
||||
=over
|
||||
|
||||
=item B<-x>, B<--one-file-system>
|
||||
|
||||
Do not cross filesystem boundaries, i.e. only count files and directories on
|
||||
the same filesystem as the directory being scanned.
|
||||
|
||||
=item B<--cross-file-system>
|
||||
|
||||
Do cross filesystem boundaries. This is the default, but can be specified to
|
||||
overrule a previously given C<-x>.
|
||||
|
||||
=item B<--exclude> I<PATTERN>
|
||||
|
||||
Exclude files that match I<PATTERN>. The files will still be displayed by
|
||||
default, but are not counted towards the disk usage statistics. This argument
|
||||
can be added multiple times to add more patterns.
|
||||
|
||||
=item B<-X> I<FILE>, B<--exclude-from> I<FILE>
|
||||
|
||||
Exclude files that match any pattern in I<FILE>. Patterns should be separated
|
||||
by a newline.
|
||||
|
||||
=item B<--include-caches>, B<--exclude-caches>
|
||||
|
||||
Include (default) or exclude directories containing CACHEDIR.TAG. The
|
||||
directories will still be displayed, but their contents will not be scanned or
|
||||
counted towards the disk usage statistics.
|
||||
L<http://www.brynosaurus.com/cachedir/>
|
||||
|
||||
=item B<-L>, B<--follow-symlinks>, B<--no-follow-symlinks>
|
||||
|
||||
Follow (or not) symlinks and count the size of the file they point to. As of
|
||||
ncdu 1.14, this option will not follow symlinks to directories and will count
|
||||
each symlinked file as a unique file (i.e. unlike how hard links are handled).
|
||||
This is subject to change in later versions.
|
||||
|
||||
=item B<--include-kernfs>, B<--exclude-kernfs>
|
||||
|
||||
(Linux only) Include (default) or exclude Linux pseudo filesystems, e.g. /proc
|
||||
(procfs), /sys (sysfs).
|
||||
|
||||
The complete list of currently known pseudo filesystems is: binfmt, bpf, cgroup,
|
||||
cgroup2, debug, devpts, proc, pstore, security, selinux, sys, trace.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Interface options
|
||||
|
||||
=over
|
||||
|
||||
=item B<-0>
|
||||
|
||||
Don't give any feedback while scanning a directory or importing a file, other
|
||||
than when a fatal error occurs. Ncurses will not be initialized until the scan
|
||||
is complete. When exporting the data with C<-o>, ncurses will not be
|
||||
initialized at all. This option is the default when exporting to standard
|
||||
output.
|
||||
|
||||
=item B<-1>
|
||||
|
||||
Similar to C<-0>, but does give feedback on the scanning progress with a single
|
||||
line of output. This option is the default when exporting to a file.
|
||||
|
||||
In some cases, the ncurses browser interface which you'll see after the
|
||||
scan/import is complete may look garbled when using this option. If you're not
|
||||
exporting to a file, C<-2> is probably a better choice.
|
||||
|
||||
=item B<-2>
|
||||
|
||||
Provide a full-screen ncurses interface while scanning a directory or importing
|
||||
a file. This is the only interface that provides feedback on any non-fatal
|
||||
errors while scanning.
|
||||
|
||||
=item B<-q>, B<--slow-ui-updates>, B<--fast-ui-updates>
|
||||
|
||||
Change the UI update interval while scanning or importing. Ncdu will update the
|
||||
screen 10 times a second by default (C<--fast-ui-updates>), this can be
|
||||
decreased to once every 2 seconds with C<-q> or C<--slow-ui-updates>. This
|
||||
feature can be used to save bandwidth over remote connections. This option has
|
||||
no effect when C<-0> is used.
|
||||
|
||||
=item B<--enable-shell>, B<--disable-shell>
|
||||
|
||||
Enable or disable shell spawning from the browser. This feature is enabled by
|
||||
default when scanning a live directory and disabled when importing from file.
|
||||
|
||||
=item B<--enable-delete>, B<--disable-delete>
|
||||
|
||||
Enable or disable the built-in file deletion feature. This feature is enabled
|
||||
by default when scanning a live directory and disabled when importing from
|
||||
file. Explicitly disabling the deletion feature can work as a safeguard to
|
||||
prevent accidental data loss.
|
||||
|
||||
=item B<--enable-refresh>, B<--disable-refresh>
|
||||
|
||||
Enable or disable directory refreshing from the browser. This feature is
|
||||
enabled by default when scanning a live directory and disabled when importing
|
||||
from file.
|
||||
|
||||
=item B<-r>
|
||||
|
||||
Read-only mode. When given once, this is an alias for C<--disable-delete>, when
|
||||
given twice it will also add C<--disable-shell>, thus ensuring that there is no
|
||||
way to modify the file system from within ncdu.
|
||||
|
||||
=item B<--si>, B<--no-si>
|
||||
|
||||
List sizes using base 10 prefixes, that is, powers of 1000 (KB, MB, etc), as
|
||||
defined in the International System of Units (SI), instead of the usual base 2
|
||||
prefixes, that is, powers of 1024 (KiB, MiB, etc).
|
||||
|
||||
=item B<--disk-usage>, B<--apparent-size>
|
||||
|
||||
Select whether to display disk usage (default) or apparent sizes. Can also be
|
||||
toggled in the browser with the 'a' key.
|
||||
|
||||
=item B<--show-hidden>, B<--hide-hidden>
|
||||
|
||||
Show (default) or hide "hidden" and excluded files. Can also be toggled in the
|
||||
browser with the 'e' key.
|
||||
|
||||
=item B<--show-itemcount>, B<--hide-itemcount>
|
||||
|
||||
Show or hide (default) the item counts column. Can also be toggled in the
|
||||
browser with the 'c' key.
|
||||
|
||||
=item B<--show-mtime>, B<--hide-mtime>
|
||||
|
||||
Show or hide (default) the last modification time column. Can also be toggled
|
||||
in the browser with the 'm' key. This option is ignored when not in extended
|
||||
mode (see C<-e>).
|
||||
|
||||
=item B<--show-graph>, B<--hide-graph>
|
||||
|
||||
Show (default) or hide the relative size bar column. Can also be toggled in the
|
||||
browser with the 'g' key.
|
||||
|
||||
=item B<--show-percent>, B<--hide-percent>
|
||||
|
||||
Show (default) or hide the relative size percent column. Can also be toggled in
|
||||
the browser with the 'g' key.
|
||||
|
||||
=item B<--graph-style> I<OPTION>
|
||||
|
||||
Change the way that the relative size bar column is drawn. Recognized values
|
||||
are I<hash> to draw ASCII C<#> characters (default and most portable),
|
||||
I<half-block> to use half-block drawing characters or I<eighth-block> to use
|
||||
eighth-block drawing characters. Eighth-block characters are the most precise
|
||||
but may not render correctly in all terminals.
|
||||
|
||||
=item B<--shared-column> I<OPTION>
|
||||
|
||||
Set to I<off> to disable the shared size column for directories, I<shared>
|
||||
(default) to display shared directory sizes as a separate column or I<unique>
|
||||
to display unique directory sizes as a separate column. These options can also
|
||||
be cycled through in the browser with the 'u' key.
|
||||
|
||||
=item B<--sort> I<COLUMN>
|
||||
|
||||
Change the default column to sort on. Accepted values are I<disk-usage> (the
|
||||
default), I<name>, I<apparent-size>, I<itemcount> or I<mtime>. The latter only
|
||||
makes sense in extended mode, see C<-e>.
|
||||
|
||||
The column can be suffixed with I<-asc> or I<-desc> to set the order to
|
||||
ascending or descending, respectively. e.g. C<--sort=name-desc> will sort by
|
||||
name in descending order.
|
||||
|
||||
=item B<--enable-natsort>, B<--disable-natsort>
|
||||
|
||||
Enable (default) or disable natural sort when sorting by file name.
|
||||
|
||||
=item B<--group-directories-first>, B<--no-group-directories-first>
|
||||
|
||||
Sort (or not) directories before files.
|
||||
|
||||
=item B<--confirm-quit>, B<--no-confirm-quit>
|
||||
|
||||
Require a confirmation before quitting ncdu. Very helpful when you accidentally
|
||||
press 'q' during or after a very long scan.
|
||||
|
||||
=item B<--confirm-delete>, B<--no-confirm-delete>
|
||||
|
||||
Require a confirmation before deleting a file or directory. Enabled by default,
|
||||
but can be disabled if you're absolutely sure you won't accidentally press 'd'.
|
||||
|
||||
=item B<--color> I<SCHEME>
|
||||
|
||||
Select a color scheme. The following schemes are recognized: I<off> to disable
|
||||
colors, I<dark> for a color scheme intended for dark backgrounds and I<dark-bg>
|
||||
for a variation of the I<dark> color scheme that also works in terminals with a
|
||||
light background.
|
||||
|
||||
The default is I<dark-bg> unless the C<NO_COLOR> environment variable is set.
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 CONFIGURATION
|
||||
|
||||
Ncdu can be configured by placing command-line options in C</etc/ncdu.conf> or
|
||||
C<$HOME/.config/ncdu/config>. If both files exist, the system configuration
|
||||
will be loaded before the user configuration, allowing users to override
|
||||
options set in the system configuration. Options given on the command line will
|
||||
override options set in the configuration files. The files will not be read at
|
||||
all when C<--ignore-config> is given on the command line.
|
||||
|
||||
The configuration file format is simply one command line option per line. Lines
|
||||
starting with C<#> are ignored. Example configuration file:
|
||||
|
||||
# Always enable extended mode
|
||||
-e
|
||||
|
||||
# Disable file deletion
|
||||
--disable-delete
|
||||
|
||||
# Exclude .git directories
|
||||
--exclude .git
|
||||
|
||||
|
||||
=head1 KEYS
|
||||
|
||||
=over
|
||||
|
||||
=item B<?>
|
||||
|
||||
Show help + keys + about screen
|
||||
|
||||
=item B<up>, B<down>, B<j>, B<k>
|
||||
|
||||
Cycle through the items
|
||||
|
||||
=item B<right>, B<enter>, B<l>
|
||||
|
||||
Open selected directory
|
||||
|
||||
=item B<left>, B<< < >>, B<h>
|
||||
|
||||
Go to parent directory
|
||||
|
||||
=item B<n>
|
||||
|
||||
Order by filename (press again for descending order)
|
||||
|
||||
=item B<s>
|
||||
|
||||
Order by filesize (press again for descending order)
|
||||
|
||||
=item B<C>
|
||||
|
||||
Order by number of items (press again for descending order)
|
||||
|
||||
=item B<a>
|
||||
|
||||
Toggle between showing disk usage and showing apparent size.
|
||||
|
||||
=item B<M>
|
||||
|
||||
Order by latest child mtime, or modified time. (press again for descending order)
|
||||
Requires the -e flag.
|
||||
|
||||
=item B<d>
|
||||
|
||||
Delete the selected file or directory. An error message will be shown when the
|
||||
contents of the directory do not match or do not exist anymore on the
|
||||
filesystem.
|
||||
|
||||
=item B<t>
|
||||
|
||||
Toggle dirs before files when sorting.
|
||||
|
||||
=item B<g>
|
||||
|
||||
Toggle between showing percentage, graph, both, or none. Percentage is relative
|
||||
to the size of the current directory, graph is relative to the largest item in
|
||||
the current directory.
|
||||
|
||||
=item B<u>
|
||||
|
||||
Toggle display of the shared / unique size column for directories that share
|
||||
hard links. This column is only visible if the current listing contains
|
||||
directories with shared hard links.
|
||||
|
||||
=item B<c>
|
||||
|
||||
Toggle display of child item counts.
|
||||
|
||||
=item B<m>
|
||||
|
||||
Toggle display of latest child mtime, or modified time. Requires the -e flag.
|
||||
|
||||
=item B<e>
|
||||
|
||||
Show/hide 'hidden' or 'excluded' files and directories. Please note that even
|
||||
though you can't see the hidden files and directories, they are still there and
|
||||
they are still included in the directory sizes. If you suspect that the totals
|
||||
shown at the bottom of the screen are not correct, make sure you haven't
|
||||
enabled this option.
|
||||
|
||||
=item B<i>
|
||||
|
||||
Show information about the current selected item.
|
||||
|
||||
=item B<r>
|
||||
|
||||
Refresh/recalculate the current directory.
|
||||
|
||||
=item B<b>
|
||||
|
||||
Spawn shell in current directory.
|
||||
|
||||
Ncdu will determine your preferred shell from the C<NCDU_SHELL> or C<SHELL>
|
||||
variable (in that order), or will call C</bin/sh> if neither are set. This
|
||||
allows you to also configure another command to be run when he 'b' key is
|
||||
pressed. For example, to spawn the L<vifm(1)> file manager instead of a shell,
|
||||
run ncdu as follows:
|
||||
|
||||
export NCDU_SHELL=vifm
|
||||
ncdu
|
||||
|
||||
Ncdu will set the C<NCDU_LEVEL> environment variable or increment it before
|
||||
spawning the shell. This variable allows you to detect when your shell is
|
||||
running from within ncdu, which can be useful to avoid nesting multiple
|
||||
instances of ncdu. Ncdu itself does not (currently) warn when attempting to run
|
||||
nested instances.
|
||||
|
||||
=item B<q>
|
||||
|
||||
Quit
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 FILE FLAGS
|
||||
|
||||
Entries in the browser interface may be prefixed by a one-character flag. These
|
||||
flags have the following meaning:
|
||||
|
||||
=over
|
||||
|
||||
=item B<!>
|
||||
|
||||
An error occurred while reading this directory.
|
||||
|
||||
=item B<.>
|
||||
|
||||
An error occurred while reading a subdirectory, so the indicated size may not be
|
||||
correct.
|
||||
|
||||
=item B<< < >>
|
||||
|
||||
File or directory is excluded from the statistics by using exclude patterns.
|
||||
|
||||
=item B<< > >>
|
||||
|
||||
Directory is on another filesystem.
|
||||
|
||||
=item B<^>
|
||||
|
||||
Directory is excluded from the statistics due to being a Linux pseudo filesystem.
|
||||
|
||||
=item B<@>
|
||||
|
||||
This is neither a file nor a folder (symlink, socket, ...).
|
||||
|
||||
=item B<H>
|
||||
|
||||
Same file was already counted (hard link).
|
||||
|
||||
=item B<e>
|
||||
|
||||
Empty directory.
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To scan and browse the directory you're currently in, all you need is a simple:
|
||||
|
||||
ncdu
|
||||
|
||||
If you want to scan a full filesystem, your root filesystem, for example, then
|
||||
you'll want to use C<-x>:
|
||||
|
||||
ncdu -x /
|
||||
|
||||
Since scanning a large directory may take a while, you can scan a directory and
|
||||
export the results for later viewing:
|
||||
|
||||
ncdu -1xo- / | gzip >export.gz
|
||||
# ...some time later:
|
||||
zcat export.gz | ncdu -f-
|
||||
|
||||
To export from a cron job, make sure to replace C<-1> with C<-0> to suppress
|
||||
any unnecessary output.
|
||||
|
||||
You can also export a directory and browse it once scanning is done:
|
||||
|
||||
ncdu -o- | tee export.file | ./ncdu -f-
|
||||
|
||||
The same is possible with gzip compression, but is a bit kludgey:
|
||||
|
||||
ncdu -o- | gzip | tee export.gz | gunzip | ./ncdu -f-
|
||||
|
||||
To scan a system remotely, but browse through the files locally:
|
||||
|
||||
ssh -C user@system ncdu -o- / | ./ncdu -f-
|
||||
|
||||
The C<-C> option to ssh enables compression, which will be very useful over
|
||||
slow links. Remote scanning and local viewing has two major advantages when
|
||||
compared to running ncdu directly on the remote system: You can browse through
|
||||
the scanned directory on the local system without any network latency, and ncdu
|
||||
does not keep the entire directory structure in memory when exporting, so you
|
||||
won't consume much memory on the remote system.
|
||||
|
||||
|
||||
=head1 HARD LINKS
|
||||
|
||||
Every disk usage analysis utility has its own way of (not) counting hard links.
|
||||
There does not seem to be any universally agreed method of handling hard links,
|
||||
and it is even inconsistent among different versions of ncdu. This section
|
||||
explains what each version of ncdu does.
|
||||
|
||||
ncdu 1.5 and below does not support any hard link detection at all: each link
|
||||
is considered a separate inode and its size is counted for every link. This
|
||||
means that the displayed directory sizes are incorrect when analyzing
|
||||
directories which contain hard links.
|
||||
|
||||
ncdu 1.6 has basic hard link detection: When a link to a previously encountered
|
||||
inode is detected, the link is considered to have a file size of zero bytes.
|
||||
Its size is not counted again, and the link is indicated in the browser
|
||||
interface with a 'H' mark. The displayed directory sizes are only correct when
|
||||
all links to an inode reside within that directory. When this is not the case,
|
||||
the sizes may or may not be correct, depending on which links were considered
|
||||
as "duplicate" and which as "original". The indicated size of the topmost
|
||||
directory (that is, the one specified on the command line upon starting ncdu)
|
||||
is always correct.
|
||||
|
||||
ncdu 1.7 and later has improved hard link detection. Each file that has more
|
||||
than two links has the "H" mark visible in the browser interface. Each hard
|
||||
link is counted exactly once for every directory it appears in. The indicated
|
||||
size of each directory is therefore, correctly, the sum of the sizes of all
|
||||
unique inodes that can be found in that directory. Note, however, that this may
|
||||
not always be same as the space that will be reclaimed after deleting the
|
||||
directory, as some inodes may still be accessible from hard links outside it.
|
||||
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
Directory hard links and firmlinks (MacOS) are not supported. They will not be
|
||||
detected as being hard links, and may thus be scanned and counted multiple
|
||||
times.
|
||||
|
||||
Some minor glitches may appear when displaying filenames that contain multibyte
|
||||
or multicolumn characters.
|
||||
|
||||
The unique and shared directory sizes are calculated based on the assumption
|
||||
that the link count of hard links does not change during a filesystem scan or
|
||||
in between refreshes. If it does, for example after deleting a hard link, then
|
||||
these numbers will be very much incorrect and a full refresh by restarting ncdu
|
||||
is needed to get correct numbers again.
|
||||
|
||||
All sizes are internally represented as a signed 64bit integer. If you have a
|
||||
directory larger than 8 EiB minus one byte, ncdu will clip its size to 8 EiB
|
||||
minus one byte. When deleting or refreshing items in a directory with a clipped
|
||||
size, the resulting sizes will be incorrect. Likewise, item counts are stored
|
||||
in a 32-bit integer, so will be incorrect in the unlikely event that you happen
|
||||
to have more than 4 billion items in a directory.
|
||||
|
||||
Please report any other bugs you may find at the bug tracker, which can be
|
||||
found on the web site at https://dev.yorhel.nl/ncdu
|
||||
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Written by Yoran Heling <projects@yorhel.nl>.
|
||||
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<du(1)>
|
||||
Loading…
Reference in a new issue