Skip to content

Commit

Permalink
Document pass-through behavior
Browse files Browse the repository at this point in the history
Adds documentation to help and man pages for legacy pass-through behavior
when force is set and destination is stdout. Documents --pass-through in
man pages
  • Loading branch information
cgbur committed Aug 15, 2022
1 parent 1b249cf commit 22ef1e8
Show file tree
Hide file tree
Showing 6 changed files with 36 additions and 9 deletions.
7 changes: 5 additions & 2 deletions programs/zstd.1
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
.
.TH "ZSTD" "1" "June 2022" "zstd 1.5.3" "User Commands"
.TH "ZSTD" "1" "August 2022" "zstd 1.5.3" "User Commands"
.
.SH "NAME"
\fBzstd\fR \- zstd, zstdmt, unzstd, zstdcat \- Compress or decompress \.zst files
Expand Down Expand Up @@ -162,7 +162,7 @@ Additionally, this can be used to limit memory for dictionary training\. This pa
\fB\-o FILE\fR: save result into \fBFILE\fR
.
.IP "\(bu" 4
\fB\-f\fR, \fB\-\-force\fR: disable input and output checks\. Allows overwriting existing files, input from console, output to stdout, operating on links, block devices, etc\.
\fB\-f\fR, \fB\-\-force\fR: disable input and output checks\. Allows overwriting existing files, input from console, output to stdout, operating on links, block devices, etc\. During decompression and when the output destination is stdout, pass\-through unrecognized formats as\-is\.
.
.IP "\(bu" 4
\fB\-c\fR, \fB\-\-stdout\fR: write to standard output (even if it is the console); keep original files unchanged\.
Expand All @@ -171,6 +171,9 @@ Additionally, this can be used to limit memory for dictionary training\. This pa
\fB\-\-[no\-]sparse\fR: enable / disable sparse FS support, to make files with many zeroes smaller on disk\. Creating sparse files may save disk space and speed up decompression by reducing the amount of disk I/O\. default: enabled when output is into a file, and disabled when output is stdout\. This setting overrides default and can force sparse mode over stdout\.
.
.IP "\(bu" 4
\fB\-\-[no\-]pass\-through\fR enable / disable passing through uncompressed files as\-is\. During decompression when pass\-through is enabled, unrecognized formats will be copied as\-is from the input to the output\. By default, pass\-through will occur when the output destination is stdout and the force (\-f) option is set\.
.
.IP "\(bu" 4
\fB\-\-rm\fR: remove source file(s) after successful compression or decompression\. If used in combination with \-o, will trigger a confirmation prompt (which can be silenced with \-f), as this is a destructive operation\.
.
.IP "\(bu" 4
Expand Down
8 changes: 8 additions & 0 deletions programs/zstd.1.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,8 @@ the last one takes effect.
* `-f`, `--force`:
disable input and output checks. Allows overwriting existing files, input
from console, output to stdout, operating on links, block devices, etc.
During decompression and when the output destination is stdout, pass-through
unrecognized formats as-is.
* `-c`, `--stdout`:
write to standard output (even if it is the console); keep original files unchanged.
* `--[no-]sparse`:
Expand All @@ -221,6 +223,12 @@ the last one takes effect.
default: enabled when output is into a file,
and disabled when output is stdout.
This setting overrides default and can force sparse mode over stdout.
* `--[no-]pass-through`
enable / disable passing through uncompressed files as-is. During
decompression when pass-through is enabled, unrecognized formats will be
copied as-is from the input to the output. By default, pass-through will
occur when the output destination is stdout and the force (-f) option is
set.
* `--rm`:
remove source file(s) after successful compression or decompression. If used in combination with
-o, will trigger a confirmation prompt (which can be silenced with -f), as this is a destructive operation.
Expand Down
5 changes: 3 additions & 2 deletions programs/zstdcli.c
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,8 @@ static void usage(FILE* f, const char* programName)
#endif
DISPLAY_F(f, " -f, --force disable input and output checks. Allows overwriting existing files,\n");
DISPLAY_F(f, " input from console, output to stdout, operating on links,\n");
DISPLAY_F(f, " block devices, etc.\n");
DISPLAY_F(f, " block devices, etc. During decompression and when the output\n");
DISPLAY_F(f, " destination is stdout, pass-through unrecognized formats as-is.\n");
DISPLAY_F(f, " --rm remove source file(s) after successful de/compression\n");
DISPLAY_F(f, " -k, --keep preserve source file(s) (default) \n");
#ifdef ZSTD_GZCOMPRESS
Expand Down Expand Up @@ -271,7 +272,7 @@ static void usage_advanced(const char* programName)
exeNameMatch(programName, ZSTD_GZCAT)) {
passThroughDefault = "enabled";
}
DISPLAYOUT(" --[no-]pass-through : passes through uncompressed files as-is (default: %s\n)", passThroughDefault);
DISPLAYOUT(" --[no-]pass-through : passes through uncompressed files as-is (default: %s)\n", passThroughDefault);
}
#endif /* ZSTD_NODECOMPRESS */

Expand Down
13 changes: 11 additions & 2 deletions programs/zstdgrep.1
Original file line number Diff line number Diff line change
@@ -1,17 +1,26 @@
.TH "ZSTDGREP" "1" "April 2022" "zstd 1.5.2" "User Commands"
.
.TH "ZSTDGREP" "1" "August 2022" "zstd 1.5.3" "User Commands"
.
.SH "NAME"
\fBzstdgrep\fR \- print lines matching a pattern in zstandard\-compressed files
.
.SH "SYNOPSIS"
\fBzstdgrep\fR [\fIgrep\-flags\fR] [\-\-] \fIpattern\fR [\fIfiles\fR \|\.\|\.\|\.]
\fBzstdgrep\fR [\fIgrep\-flags\fR] [\-\-] \fIpattern\fR [\fIfiles\fR \.\.\.]
.
.SH "DESCRIPTION"
\fBzstdgrep\fR runs \fBgrep (1)\fR on files, or \fBstdin\fR if no files argument is given, after decompressing them with \fBzstdcat (1)\fR\.
.
.P
The grep\-flags and pattern arguments are passed on to \fBgrep (1)\fR\. If an \fB\-e\fR flag is found in the \fBgrep\-flags\fR, \fBzstdgrep\fR will not look for a pattern argument\.
.
.P
Note that modern \fBgrep\fR alternatives such as \fBripgrep\fR (\fBrg\fR) support \fBzstd\fR\-compressed files out of the box, and can prove better alternatives than \fBzstdgrep\fR notably for unsupported complex pattern searches\. Note though that such alternatives may also feature some minor command line differences\.
.
.SH "EXIT STATUS"
In case of missing arguments or missing pattern, 1 will be returned, otherwise 0\.
.
.SH "SEE ALSO"
\fBzstd (1)\fR
.
.SH "AUTHORS"
Thomas Klausner \fIwiz@NetBSD\.org\fR
9 changes: 7 additions & 2 deletions programs/zstdless.1
Original file line number Diff line number Diff line change
@@ -1,9 +1,14 @@
.TH "ZSTDLESS" "1" "April 2022" "zstd 1.5.2" "User Commands"
.
.TH "ZSTDLESS" "1" "August 2022" "zstd 1.5.3" "User Commands"
.
.SH "NAME"
\fBzstdless\fR \- view zstandard\-compressed files
.
.SH "SYNOPSIS"
\fBzstdless\fR [\fIflags\fR] [\fIfile\fR \|\.\|\.\|\.]
\fBzstdless\fR [\fIflags\fR] [\fIfile\fR \.\.\.]
.
.SH "DESCRIPTION"
\fBzstdless\fR runs \fBless (1)\fR on files or stdin, if no files argument is given, after decompressing them with \fBzstdcat (1)\fR\.
.
.SH "SEE ALSO"
\fBzstd (1)\fR
3 changes: 2 additions & 1 deletion tests/cli-tests/basic/help.sh.stdout.glob
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ Compress or uncompress FILEs (with no FILE or when FILE is `-`, read from standa
-d, --decompress decompression
-f, --force disable input and output checks. Allows overwriting existing files,
input from console, output to stdout, operating on links,
block devices, etc.
block devices, etc. During decompression and when the output
destination is stdout, pass-through unrecognized formats as-is.
--rm remove source file(s) after successful de/compression
-k, --keep preserve source file(s) (default)
-D DICT use DICT as Dictionary for compression or decompression
Expand Down

0 comments on commit 22ef1e8

Please sign in to comment.