From 60010a4b32f32552714f0da264ba20fceb743135 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Mon, 9 Feb 2026 14:30:39 +0100 Subject: [PATCH] Documentation of the new commands --- HISTORY | 16 +++++++++++----- doc/snapraid.1 | 42 +++++++++++++++++++++++++++++++++++++++--- doc/snapraid.d | 40 +++++++++++++++++++++++++++++++++++++--- doc/snapraid.txt | 42 +++++++++++++++++++++++++++++++++++++++--- 4 files changed, 126 insertions(+), 14 deletions(-) diff --git a/HISTORY b/HISTORY index bc222f58..6258721b 100644 --- a/HISTORY +++ b/HISTORY @@ -16,8 +16,14 @@ SnapRAID HISTORY * Added a new locate command to map physical file offsets within the parity volume. This feature facilitates diagnostic analysis of the parity distribution. It supports the -t, --tail option to filter files located - specifically at the end of the parity file. This option handles size - suffixes K, M, and G using decimal SI units [Ralf1108]. + specifically at the end of the parity file [Ralf1108]. + * Added new option `-W, --force-realloc-tail SIZE` for the `sync` command. + This option works like `--force-realloc` but applies only to the + specified tail portion (last SIZE bytes) of the parity file. + Its main purpose and result is to shrink the size of the parity file by + reclaiming unused space ("holes") that may exist in the parity due to + previous fragmentation, allowing to compact the parity toward the beginning + [Ralf1108]. * Added detection of the smartctl executable. Improves reliability when running under sudo or in environments where /sbin and /usr/sbin are not in PATH. * Avoided saving the content file when it was not strictly necessary. @@ -54,7 +60,7 @@ SnapRAID HISTORY dependent on the hard disk vendor. * Added a new "smartignore" configuration option to ignore specific SMART attributes. - * Supported UUID in macOS [Nasado] + * Supported UUID in macOS [Nasado]. * Windows binaries built with gcc 11.5.0 using the MXE cross compiler at commit 8c4378fa2b55bc28515b23e96e05d03e671d9b90 with targets i686-w64-mingw32.static and x86_64-w64-mingw32.static and optimization -O2. @@ -92,12 +98,12 @@ SnapRAID HISTORY files and the final state of the files like 'recovered' or 'unrecovered'. The previous behavior is available with the -b, --filter-block-error option. * Improved the speed of the filtering in 'fix' and 'check'. This phase - happens after the "Selecting..." message. [UhClem] + happens after the "Selecting..." message [UhClem]. 11.5 2020/05 ============ * Removed the default -march=native to allow deployment in any machine. - * Fixed typos [Andrea Gelmini] + * Fixed typos [Andrea Gelmini]. 11.4 2020/05 ============ diff --git a/doc/snapraid.1 b/doc/snapraid.1 index fba01407..cdc0bb6b 100644 --- a/doc/snapraid.1 +++ b/doc/snapraid.1 @@ -29,6 +29,10 @@ snapraid [\-c, \-\-conf CONFIG] [\-s, \-\-spin\-down\-on\-error] [\-w, \-\-bw\-limit RATE] .PD 0 .PP +.PD + [\-t, \-\-tail] +.PD 0 +.PP .PD [\-Z, \-\-force\-zero] [\-E, \-\-force\-empty] .PD 0 @@ -42,7 +46,7 @@ snapraid [\-c, \-\-conf CONFIG] .PD 0 .PP .PD - [\-R, \-\-force\-realloc] + [\-R, \-\-force\-realloc] [\-W, \-\-force\-realloc\-tail] .PD 0 .PP .PD @@ -66,7 +70,7 @@ snapraid [\-c, \-\-conf CONFIG] .PD 0 .PP .PD - |list|dup|pool|devices|touch|rehash + |list|dup|pool|devices|touch|rehash|locate .PD 0 .PD .PP @@ -995,6 +999,13 @@ You can check the rehash state using \`status\`. During the rehash, SnapRAID maintains full functionality, with the only exception that \`dup\` cannot detect duplicated files using a different hash. +.SS locate +Locate files stored in the parity disks. For each matching file, it +prints its location within the parity file and the number of fragments +it occupies. +.PP +You can use the \-t, \-\-tail option to restrict the operation to files +using only the specified tail portion of the parity. .SH OPTIONS SnapRAID provides the following options: .TP @@ -1105,7 +1116,14 @@ stopped even when a command fails. .B \-w, \-\-bw\-limit RATE Applies a global bandwidth limit for all disks. The RATE is the number of bytes per second. You can specify a multiplier -such as K, M, or G (e.g., \-\-bw\-limit 1G). +such as K, M, G, or T (e.g., \-\-bw\-limit 1G). +.TP +.B \-t, \-\-tail SIZE +Limit file listing to those using no more than the specified +tail size of the parity disks. +You can use multipliers such as K, M, G, or T (e.g. \-\-tail 1G). +This option is only valid when used together with the \`locate\` +command. .TP .B \-A, \-\-stats Enables an extended status view that shows additional information. @@ -1202,6 +1220,24 @@ WARNING! This option is for experts only, and it is highly recommended not to use it. You DO NOT have data protection during the \`sync\` operation. .TP +.B \-W, \-\-force\-realloc\-tail SIZE +Works like \-R, \-\-force\-realloc, but limited to the specified +tail portion (last SIZE bytes) of each parity file. +It forces reallocation (movement) of any file fragments/blocks +currently stored in that tail section, allowing them to be +placed anywhere in the parity file where free space is +available (including existing holes). +The main purpose of this option is to shrink the on\-disk size +of the parity file. If the reallocation successfully clears +the entire tail section (no blocks remain using it), the +parity file is truncated, reclaiming the unused tail space. +You can use multipliers such as K, M, G, or T (e.g. +\-\-force\-realloc\-tail 1G). +WARNING! This option is for experts only, and it is highly +recommended not to use it. +You DO NOT have data protection during the \`sync\` operation +for the affected files. +.TP .B \-l, \-\-log FILE Writes a detailed log to the specified file. If this option is not specified, unexpected errors are printed diff --git a/doc/snapraid.d b/doc/snapraid.d index 5ef02784..c8aa0f6c 100644 --- a/doc/snapraid.d +++ b/doc/snapraid.d @@ -9,16 +9,17 @@ Synopsis : [-p, --plan PERC|bad|new|full] : [-o, --older-than DAYS] [-l, --log FILE] : [-s, --spin-down-on-error] [-w, --bw-limit RATE] + : [-t, --tail] : [-Z, --force-zero] [-E, --force-empty] : [-U, --force-uuid] [-D, --force-device] : [-N, --force-nocopy] [-F, --force-full] - : [-R, --force-realloc] + : [-R, --force-realloc] [-W, --force-realloc-tail] : [-S, --start BLKSTART] [-B, --count BLKCOUNT] : [-L, --error-limit NUMBER] : [-A, --stats] : [-v, --verbose] [-q, --quiet] : status|smart|probe|up|down|diff|sync|scrub|fix|check - : |list|dup|pool|devices|touch|rehash + : |list|dup|pool|devices|touch|rehash|locate :snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT] @@ -717,6 +718,14 @@ Commands with the only exception that `dup` cannot detect duplicated files using a different hash. + locate + Locate files stored in the parity disks. For each matching file, it + prints its location within the parity file and the number of fragments + it occupies. + + You can use the -t, --tail option to restrict the operation to files + using only the specified tail portion of the parity. + Options SnapRAID provides the following options: @@ -827,7 +836,14 @@ Options -w, --bw-limit RATE Applies a global bandwidth limit for all disks. The RATE is the number of bytes per second. You can specify a multiplier - such as K, M, or G (e.g., --bw-limit 1G). + such as K, M, G, or T (e.g., --bw-limit 1G). + + -t, --tail SIZE + Limit file listing to those using no more than the specified + tail size of the parity disks. + You can use multipliers such as K, M, G, or T (e.g. --tail 1G). + This option is only valid when used together with the `locate` + command. -A, --stats Enables an extended status view that shows additional information. @@ -924,6 +940,24 @@ Options recommended not to use it. You DO NOT have data protection during the `sync` operation. + -W, --force-realloc-tail SIZE + Works like -R, --force-realloc, but limited to the specified + tail portion (last SIZE bytes) of each parity file. + It forces reallocation (movement) of any file fragments/blocks + currently stored in that tail section, allowing them to be + placed anywhere in the parity file where free space is + available (including existing holes). + The main purpose of this option is to shrink the on-disk size + of the parity file. If the reallocation successfully clears + the entire tail section (no blocks remain using it), the + parity file is truncated, reclaiming the unused tail space. + You can use multipliers such as K, M, G, or T (e.g. + --force-realloc-tail 1G). + WARNING! This option is for experts only, and it is highly + recommended not to use it. + You DO NOT have data protection during the `sync` operation + for the affected files. + -l, --log FILE Writes a detailed log to the specified file. If this option is not specified, unexpected errors are printed diff --git a/doc/snapraid.txt b/doc/snapraid.txt index 80b3a8e6..47f5cfb6 100644 --- a/doc/snapraid.txt +++ b/doc/snapraid.txt @@ -13,16 +13,17 @@ snapraid [-c, --conf CONFIG] [-p, --plan PERC|bad|new|full] [-o, --older-than DAYS] [-l, --log FILE] [-s, --spin-down-on-error] [-w, --bw-limit RATE] + [-t, --tail] [-Z, --force-zero] [-E, --force-empty] [-U, --force-uuid] [-D, --force-device] [-N, --force-nocopy] [-F, --force-full] - [-R, --force-realloc] + [-R, --force-realloc] [-W, --force-realloc-tail] [-S, --start BLKSTART] [-B, --count BLKCOUNT] [-L, --error-limit NUMBER] [-A, --stats] [-v, --verbose] [-q, --quiet] status|smart|probe|up|down|diff|sync|scrub|fix|check - |list|dup|pool|devices|touch|rehash + |list|dup|pool|devices|touch|rehash|locate snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT] @@ -773,6 +774,16 @@ During the rehash, SnapRAID maintains full functionality, with the only exception that `dup` cannot detect duplicated files using a different hash. +5.17 locate +----------- + +Locate files stored in the parity disks. For each matching file, it +prints its location within the parity file and the number of fragments +it occupies. + +You can use the -t, --tail option to restrict the operation to files +using only the specified tail portion of the parity. + 6 OPTIONS ========= @@ -886,7 +897,14 @@ SnapRAID provides the following options: -w, --bw-limit RATE Applies a global bandwidth limit for all disks. The RATE is the number of bytes per second. You can specify a multiplier - such as K, M, or G (e.g., --bw-limit 1G). + such as K, M, G, or T (e.g., --bw-limit 1G). + + -t, --tail SIZE + Limit file listing to those using no more than the specified + tail size of the parity disks. + You can use multipliers such as K, M, G, or T (e.g. --tail 1G). + This option is only valid when used together with the `locate` + command. -A, --stats Enables an extended status view that shows additional information. @@ -983,6 +1001,24 @@ SnapRAID provides the following options: recommended not to use it. You DO NOT have data protection during the `sync` operation. + -W, --force-realloc-tail SIZE + Works like -R, --force-realloc, but limited to the specified + tail portion (last SIZE bytes) of each parity file. + It forces reallocation (movement) of any file fragments/blocks + currently stored in that tail section, allowing them to be + placed anywhere in the parity file where free space is + available (including existing holes). + The main purpose of this option is to shrink the on-disk size + of the parity file. If the reallocation successfully clears + the entire tail section (no blocks remain using it), the + parity file is truncated, reclaiming the unused tail space. + You can use multipliers such as K, M, G, or T (e.g. + --force-realloc-tail 1G). + WARNING! This option is for experts only, and it is highly + recommended not to use it. + You DO NOT have data protection during the `sync` operation + for the affected files. + -l, --log FILE Writes a detailed log to the specified file. If this option is not specified, unexpected errors are printed