[PATCH 4/4] hardlink: (man,usage) sort the options mostly alphabetically
Benno Schulenberg <[email protected]>
| Newsgroups | org.kernel.vger.util-linux |
|---|---|
| Message-ID | <[email protected]> |
Also, improve some markup and wording and grammar. Signed-off-by: Benno Schulenberg <[email protected]> --- misc-utils/hardlink.1.adoc | 55 +++++++++++++++++++------------------- misc-utils/hardlink.c | 22 +++++++-------- 2 files changed, 39 insertions(+), 38 deletions(-) diff --git a/misc-utils/hardlink.1.adoc b/misc-utils/hardlink.1.adoc index e09572f6c..5788014d2 100644 --- a/misc-utils/hardlink.1.adoc +++ b/misc-utils/hardlink.1.adoc @@ -65,21 +65,21 @@ For example, *hardlink foo/ bar/* will link files in bar/ to equal files in the *-i*, *--include* _regex_:: A regular expression to include files. If the option *--exclude* has been given, this option re-includes files which would otherwise be excluded. If the option is used without *--exclude*, only files matched by the pattern are included. +*-l*, *--list-duplicates*:: +Don't link anything, but list the absolute path of every duplicate file, one per line, preceded by a unique 16-byte discriminator and a tab. + *-m*, *--maximize*:: Among equal files, keep the file with the highest link count. *-M*, *--minimize*:: Among equal files, keep the file with the lowest link count. +*--mount*:: +Do not traverse directories on different filesystems (remain within the same filesystem). + *-n*, *--dry-run*:: Do not act, just print what would happen. -*-l*, *--list-duplicates*:: -Don't link anything, but list the absolute path of every duplicate file, one per line, preceded by a unique 16-byte discriminator and a tab. - -*-z*, *--zero*:: -Separate lines with a NUL instead of a newline in *-l* mode. - *-o*, *--ignore-owner*:: Link and compare files even if their owner information (user and group) differs. Results may be unpredictable. @@ -98,6 +98,22 @@ file content block (see *--io-size*), these checksums are cached for the next co size is important for large files or a large sets of files of the same size. The default is 10MiB. +*--reflink*[**=**_when_]:: +Create copy-on-write clones (aka reflinks) rather than hardlinks. The reflinked files +share only on-disk data, but the file mode and owner can be different. It's recommended +to use this option together with the *--ignore-owner* and *--ignore-mode* options. +This option implies *--skip-reflinks* to ignore already cloned files. ++ +The optional argument _when_ can be *never*, *always*, or *auto*. If the _when_ argument +is omitted, it defaults to *auto*, which means that *hardlink* checks the filesystem type +and uses reflinks on BTRFS and XFS only, and falls back to hardlinks when creating a +reflink is impossible. +The argument *always* disables filesystem-type detection and the fallback to hardlinks, +which means that only reflinks are allowed. + +*--skip-reflinks*:: +Ignore already cloned files. This option may be used without *--reflink* when creating classic hardlinks. + *-s*, *--minimum-size* _size_:: The minimum size to consider. By default this is 1, so empty files will not be linked. The _size_ argument may be followed by the multiplicative suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g., "K" has the same meaning as "KiB"). @@ -116,33 +132,18 @@ A regular expression that excludes files from being compared and linked. This op *--exclude-subtree* _regex_:: A regular expression that excludes entire directories from being compared and linked. This option can also be used multiple times. -*--mount*:: -Do not traverse directories on different filesystems (remain within the same filesystem). - *-X*, *--respect-xattrs*:: Only try to link files with the same extended attributes. *-y*, *--method* _name_:: Set the file content comparison method. The currently supported methods are -sha256, sha1, crc32c and memcmp. The default is sha256, or memcmp if Linux -Crypto API is not available. The methods based on checksums are implemented in -zero-copy way, in this case file contents are not copied to the userspace and all -calculation is done in kernel. +*sha256*, *sha1*, *crc32c*, and *memcmp*. The default is *sha256*, or *memcmp* if the +Linux Crypto API is not available. The methods based on checksums are implemented in +a zero-copy way, which means that file contents are not copied to userspace and all +calculation is done in the kernel. -*--reflink*[**=**_when_]:: -Create copy-on-write clones (aka reflinks) rather than hardlinks. The reflinked files -share only on-disk data, but the file mode and owner can be different. It's recommended -to use it with *--ignore-owner* and *--ignore-mode* options. This option implies -*--skip-reflinks* to ignore already cloned files. -+ -The optional argument _when_ can be *never*, *always*, or *auto*. If the _when_ argument -is omitted, it defaults to *auto*, in this case, *hardlink* checks filesystem type and -uses reflinks on BTRFS and XFS only, and fallback to hardlinks when creating reflink is impossible. -The argument *always* disables filesystem type detection and fallback to hardlinks, in this case, -only reflinks are allowed. - -*--skip-reflinks*:: -Ignore already cloned files. This option may be used without *--reflink* when creating classic hardlinks. +*-z*, *--zero*:: +Separate lines with a NUL byte instead of a newline (for *-l*). include::man-common/help-version.adoc[] diff --git a/misc-utils/hardlink.c b/misc-utils/hardlink.c index 5365e5370..cd28fe018 100644 --- a/misc-utils/hardlink.c +++ b/misc-utils/hardlink.c @@ -1191,24 +1191,28 @@ static void __attribute__((__noreturn__)) usage(void) fputs(USAGE_OPTIONS, out); fputs(_(" -c, --content compare only file contents, same as -pot\n"), out); fputs(_(" -b, --io-size <size> I/O buffer size for file reading\n" - " (speedup, using more RAM)\n"), out); + " (speedup, using more RAM)\n"), out); fputs(_(" -d, --respect-dir directory names have to be identical\n"), out); fputs(_(" -f, --respect-name filenames have to be identical\n"), out); + fputs(_(" -F, --prioritize-trees files found in the earliest specified top-level\n" + " directory have higher priority (but this has\n" + " lower precedence than --maximize/--minimize)\n"), out); fputs(_(" -i, --include <regex> regular expression to include files/dirs\n"), out); + fputs(_(" -l, --list-duplicates just list paths of duplicates, don't link them\n"), out); fputs(_(" -m, --maximize keep the file with the most links\n"), out); fputs(_(" -M, --minimize keep the file with the fewest links\n"), out); + fputs(_(" --mount stay within the same filesystem\n"), out); fputs(_(" -n, --dry-run don't actually link anything\n"), out); - fputs(_(" -l, --list-duplicates just list paths of duplicates, don't link them\n"), out); - fputs(_(" -z, --zero delimit output with NULs instead of newlines\n"), out); fputs(_(" -o, --ignore-owner ignore owner changes\n"), out); - fputs(_(" -F, --prioritize-trees files found in the earliest specified top-level\n" - " directory have higher priority (lower precedence\n" - " than minimize/maximize)\n"), out); fputs(_(" -O, --keep-oldest keep the oldest file of multiple equal files\n" " (lower precedence than minimize/maximize)\n"), out); fputs(_(" -p, --ignore-mode ignore changes of file mode\n"), out); fputs(_(" -q, --quiet quiet mode - don't print anything\n"), out); fputs(_(" -r, --cache-size <size> memory limit for cached file content data\n"), out); +#ifdef USE_REFLINK + fputs(_(" --reflink[=<when>] create clone/CoW copies (auto, always, never)\n"), out); + fputs(_(" --skip-reflinks skip already cloned files (enabled on --reflink)\n"), out); +#endif fputs(_(" -s, --minimum-size <size> minimum size for files\n"), out); fputs(_(" -S, --maximum-size <size> maximum size for files\n"), out); fputs(_(" -t, --ignore-time ignore timestamps (when testing for equality)\n"), out); @@ -1217,16 +1221,12 @@ static void __attribute__((__noreturn__)) usage(void) #ifdef USE_SKIP_SUBTREE fputs(_(" --exclude-subtree <regex> regular expression to exclude directories\n"), out); #endif - fputs(_(" --mount stay within the same filesystem\n"), out); #ifdef USE_XATTR fputs(_(" -X, --respect-xattrs respect extended attributes\n"), out); #endif fputs(_(" -y, --method <name> file content comparison method\n"), out); + fputs(_(" -z, --zero delimit output with NULs instead of newlines\n"), out); -#ifdef USE_REFLINK - fputs(_(" --reflink[=<when>] create clone/CoW copies (auto, always, never)\n"), out); - fputs(_(" --skip-reflinks skip already cloned files (enabled on --reflink)\n"), out); -#endif fputs(USAGE_SEPARATOR, out); fprintf(out, USAGE_HELP_OPTIONS(28)); fprintf(out, USAGE_MAN_TAIL("hardlink(1)")); -- 2.48.1