diff options
-rw-r--r-- | doc/ncdu.pod | 548 |
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)> |