summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/ncdu.pod548
1 files changed, 0 insertions, 548 deletions
diff --git a/doc/ncdu.pod b/doc/ncdu.pod
deleted file mode 100644
index 32285db..0000000
--- a/doc/ncdu.pod
+++ /dev/null
@@ -1,548 +0,0 @@
-=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<--exclude-firmlinks>, B<--follow-firmlinks>
-
-(MacOS only) Exclude or follow firmlinks.
-
-=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<--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<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 are not supported. They will not be detected as being hard
-links, and will thus be scanned and counted multiple times.
-
-Some minor glitches may appear when displaying filenames that contain multibyte
-or multicolumn characters.
-
-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 items in a directory with a clipped size, the
-resulting sizes will be incorrect.
-
-Item counts are stored in a signed 32-bit integer without overflow detection.
-If you have a directory with more than 2 billion files, quite literally
-anything can happen.
-
-On macOS 10.15 and later, running ncdu on the root directory without
-`--exclude-firmlinks` may cause directories to be scanned and counted multiple
-times. Firmlink cycles are currently (1.16) not detected, so it may also cause
-ncdu to get stuck in an infinite loop and eventually run out of memory.
-
-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)>