Merge branch 'PR/Benno-23May' of https://github.com/karelzak/util-linux-work

karelzak · karelzak · commit 27dd83b942c9 · 2025-05-29T12:02:53.000+02:00
* 'PR/Benno-23May' of https://github.com/karelzak/util-linux-work: hardlink: (man,usage) sort the options mostly alphabetically hardlink: (usage) improve the descriptions of three options hardlink: (usage) remove mistaken period from two option descriptions hexdump: (man) put a list item on a single line, to avoid a warning
diff --git 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.
-
-*--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.
+*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.
 
-*--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
@@ -1191,43 +1191,42 @@ 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(_(" -m, --maximize             maximize the hardlink count, remove the file with\n"
-	        "                              lowest hardlink count\n"), out);
-	fputs(_(" -M, --minimize             reverse the meaning of -m\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      print every group of duplicate files\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);
-	fputs(_(" -s, --minimum-size <size>  minimum size for files.\n"), out);
-	fputs(_(" -S, --maximum-size <size>  maximum size for files.\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);
 	fputs(_(" -v, --verbose              verbose output (repeat for more verbosity)\n"), out);
 	fputs(_(" -x, --exclude <regex>      regular expression to exclude files\n"), out);
 #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)"));
diff --git a/text-utils/hexdump.1.adoc b/text-utils/hexdump.1.adoc
@@ -118,8 +118,7 @@ The format is required and must be surrounded by double quote (" ") marks. It is
 
 . An asterisk (*) may not be used as a field width or precision.
 
-. A byte count or field precision _is_ required for each *s* conversion character
-(unlike the *fprintf*(3) default which prints the entire string if the precision is unspecified).
+. A byte count or field precision _is_ required for each *s* conversion character (unlike the *fprintf*(3) default which prints the entire string if the precision is unspecified).
 
 . The conversion characters *h*, *l*, *n*, *p*, and *q* are not supported.
 
