diff --git a/programs/zstdcli.c b/programs/zstdcli.c index b3d06e809..7ff18dcb0 100644 --- a/programs/zstdcli.c +++ b/programs/zstdcli.c @@ -52,12 +52,12 @@ /*-************************************ * Constants **************************************/ -#define COMPRESSOR_NAME "zstd command line interface" +#define COMPRESSOR_NAME "Zstandard CLI" #ifndef ZSTD_VERSION # define ZSTD_VERSION "v" ZSTD_VERSION_STRING #endif #define AUTHOR "Yann Collet" -#define WELCOME_MESSAGE "*** %s %i-bits %s, by %s ***\n", COMPRESSOR_NAME, (int)(sizeof(size_t)*8), ZSTD_VERSION, AUTHOR +#define WELCOME_MESSAGE "*** %s (%i-bit) %s, by %s ***\n", COMPRESSOR_NAME, (int)(sizeof(size_t)*8), ZSTD_VERSION, AUTHOR #define ZSTD_ZSTDMT "zstdmt" #define ZSTD_UNZSTD "unzstd" @@ -143,160 +143,174 @@ static int exeNameMatch(const char* exeName, const char* test) */ static void usage(FILE* f, const char* programName) { - DISPLAY_F(f, "Usage: %s [OPTION]... [FILE]... [-o file]\n", programName); - DISPLAY_F(f, "Compress or uncompress FILEs (with no FILE or when FILE is `-`, read from standard input).\n\n"); - DISPLAY_F(f, " -o file result stored into `file` (only 1 output file)\n"); -#ifndef ZSTD_NOCOMPRESS - DISPLAY_F(f, " -1 .. -%d compression level (faster .. better; default: %d)\n", ZSTDCLI_CLEVEL_MAX, ZSTDCLI_CLEVEL_DEFAULT); -#endif -#ifndef ZSTD_NODECOMPRESS - DISPLAY_F(f, " -d, --decompress decompression\n"); -#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. 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"); + DISPLAY_F(f, "Compress or decompress the INPUT file(s); reads from STDIN if INPUT is `-` or not provided.\n\n"); + DISPLAY_F(f, "Usage: %s [OPTIONS...] [INPUT... | -] [-o OUTPUT]\n\n", programName); + DISPLAY_F(f, "Options:\n"); + DISPLAY_F(f, " -o OUTPUT Write output to a single file, OUTPUT.\n"); + DISPLAY_F(f, " -k, --keep Preserve INPUT file(s). [Default] \n"); + DISPLAY_F(f, " --rm Remove INPUT file(s) after successful (de)compression.\n"); #ifdef ZSTD_GZCOMPRESS if (exeNameMatch(programName, ZSTD_GZ)) { /* behave like gzip */ - DISPLAY_F(f, " -n, --no-name do not store original filename when compressing\n"); + DISPLAY_F(f, " -n, --no-name Do not store original filename when compressing.\n\n"); } #endif - DISPLAY_F(f, " -D DICT use DICT as Dictionary for compression or decompression\n"); - DISPLAY_F(f, " -h display usage and exit\n"); - DISPLAY_F(f, " -H,--help display long help and exit\n"); + DISPLAY_F(f, "\n"); +#ifndef ZSTD_NOCOMPRESS + DISPLAY_F(f, " -# Desired compression level, where `#` is a number between 1 and %d;\n", ZSTDCLI_CLEVEL_MAX); + DISPLAY_F(f, " lower numbers provide faster compression, higher numbers yield\n"); + DISPLAY_F(f, " better compression ratios. [Default: %d]\n\n", ZSTDCLI_CLEVEL_DEFAULT); +#endif +#ifndef ZSTD_NODECOMPRESS + DISPLAY_F(f, " -d, --decompress Perform decompression.\n"); +#endif + DISPLAY_F(f, " -D DICT Use DICT as the dictionary for compression or decompression.\n\n"); + DISPLAY_F(f, " -f, --force Disable input and output checks. Allows overwriting existing files,\n"); + DISPLAY_F(f, " receiving input from the console, printing ouput to STDOUT, and\n"); + DISPLAY_F(f, " operating on links, block devices, etc. Unrecognized formats will be\n"); + DISPLAY_F(f, " passed-through through as-is.\n\n"); + + DISPLAY_F(f, " -h Display short usage and exit.\n"); + DISPLAY_F(f, " -H, --help Display full help and exit.\n"); + DISPLAY_F(f, " -V, --version Display the program version and exit.\n"); DISPLAY_F(f, "\n"); } static void usage_advanced(const char* programName) { DISPLAYOUT(WELCOME_MESSAGE); + DISPLAYOUT("\n"); usage(stdout, programName); - DISPLAYOUT("Advanced options :\n"); - DISPLAYOUT(" -V, --version display Version number and exit\n"); + DISPLAYOUT("Advanced options:\n"); + DISPLAYOUT(" -c, --stdout Write to STDOUT (even if it is a console) and keep the INPUT file(s).\n\n"); - DISPLAYOUT(" -c, --stdout write to standard output (even if it is the console), keep original file\n"); - - DISPLAYOUT(" -v, --verbose verbose mode; specify multiple times to increase verbosity\n"); - DISPLAYOUT(" -q, --quiet suppress warnings; specify twice to suppress errors too\n"); - DISPLAYOUT(" --[no-]progress forcibly display, or never display the progress counter\n"); - DISPLAYOUT(" note: any (de)compressed output to terminal will mix with progress counter text\n"); + DISPLAYOUT(" -v, --verbose Enable verbose output; pass multiple times to increase verbosity.\n"); + DISPLAYOUT(" -q, --quiet Suppress warnings; pass twice to suppress errors.\n"); +#ifndef ZSTD_NOTRACE + DISPLAYOUT(" --trace LOG Log tracing information to LOG.\n"); +#endif + DISPLAYOUT("\n"); + DISPLAYOUT(" --[no-]progress Forcibly show/hide the progress counter. NOTE: Any (de)compressed\n"); + DISPLAYOUT(" output to terminal will mix with progress counter text.\n\n"); #ifdef UTIL_HAS_CREATEFILELIST - DISPLAYOUT(" -r operate recursively on directories\n"); - DISPLAYOUT(" --filelist FILE read list of files to operate upon from FILE\n"); - DISPLAYOUT(" --output-dir-flat DIR : processed files are stored into DIR\n"); + DISPLAYOUT(" -r Operate recursively on directories.\n"); + DISPLAYOUT(" --filelist LIST Read a list of files to operate on from LIST.\n"); + DISPLAYOUT(" --output-dir-flat DIR Store processed files in DIR.\n"); #endif #ifdef UTIL_HAS_MIRRORFILELIST - DISPLAYOUT(" --output-dir-mirror DIR : processed files are stored into DIR respecting original directory structure\n"); + DISPLAYOUT(" --output-dir-mirror DIR Store processed files in DIR, respecting original directory structure.\n"); #endif if (AIO_supported()) - DISPLAYOUT(" --[no-]asyncio use asynchronous IO (default: enabled)\n"); + DISPLAYOUT(" --[no-]asyncio Use asynchronous IO. [Default: Enabled]\n"); + DISPLAYOUT("\n"); #ifndef ZSTD_NOCOMPRESS - DISPLAYOUT(" --[no-]check during compression, add XXH64 integrity checksum to frame (default: enabled)\n"); + DISPLAYOUT(" --[no-]check Add XXH64 integrity checksums during compression. [Default: Add, Validate]\n"); #ifndef ZSTD_NODECOMPRESS - DISPLAYOUT(" if specified with -d, decompressor will ignore/validate checksums in compressed frame (default: validate)\n"); + DISPLAYOUT(" If `-d` is present, ignore/validate checksums during decompression.\n"); #endif #else #ifdef ZSTD_NOCOMPRESS - DISPLAYOUT(" --[no-]check during decompression, ignore/validate checksums in compressed frame (default: validate)"); + DISPLAYOUT(" --[no-]check Ignore/validate checksums during decompression. [Default: Validate]"); #endif - DISPLAYOUT("\n"); #endif /* ZSTD_NOCOMPRESS */ -#ifndef ZSTD_NOTRACE - DISPLAYOUT(" --trace FILE log tracing information to FILE\n"); -#endif - DISPLAYOUT(" -- all arguments after \"--\" are treated as files\n"); + DISPLAYOUT("\n"); + DISPLAYOUT(" -- Treat remaining arguments after `--` as files.\n"); #ifndef ZSTD_NOCOMPRESS DISPLAYOUT("\n"); - DISPLAYOUT("Advanced compression options :\n"); - DISPLAYOUT(" --ultra enable levels beyond %i, up to %i (requires more memory)\n", ZSTDCLI_CLEVEL_MAX, ZSTD_maxCLevel()); - DISPLAYOUT(" --fast[=#] switch to very fast compression levels (default: %u)\n", 1); + DISPLAYOUT("Advanced compression options:\n"); + DISPLAYOUT(" --ultra Enable levels beyond %i, up to %i; requires more memory.\n", ZSTDCLI_CLEVEL_MAX, ZSTD_maxCLevel()); + DISPLAYOUT(" --fast[=#] Use to very fast compression levels. [Default: %u]\n", 1); #ifdef ZSTD_GZCOMPRESS if (exeNameMatch(programName, ZSTD_GZ)) { /* behave like gzip */ - DISPLAYOUT(" --best compatibility alias for -9 \n"); - DISPLAYOUT(" --no-name do not store original filename when compressing\n"); + DISPLAYOUT(" --best Compatibility alias for `-9`.\n"); } #endif - DISPLAYOUT(" --long[=#] enable long distance matching with given window log (default: %u)\n", g_defaultMaxWindowLog); - DISPLAYOUT(" --patch-from=FILE : specify the file to be used as a reference point for zstd's diff engine. \n"); - DISPLAYOUT(" --adapt dynamically adapt compression level to I/O conditions\n"); + DISPLAYOUT(" --adapt Dynamically adapt compression level to I/O conditions.\n"); + DISPLAYOUT(" --long[=#] Enable long distance matching with window log #. [Default: %u]\n", g_defaultMaxWindowLog); + DISPLAYOUT(" --patch-from=REF Use REF as the reference point for Zstandard's diff engine. \n\n"); # ifdef ZSTD_MULTITHREAD - DISPLAYOUT(" -T# spawn # compression threads (default: 1, 0==# cores) \n"); - DISPLAYOUT(" -B# select size of each job (default: 0==automatic) \n"); - DISPLAYOUT(" --single-thread use a single thread for both I/O and compression (result slightly different than -T1) \n"); - DISPLAYOUT(" --auto-threads={physical,logical} : use either physical cores or logical cores as default when specifying -T0 (default: physical)\n"); - DISPLAYOUT(" --rsyncable compress using a rsync-friendly method (-B sets block size) \n"); + DISPLAYOUT(" -T# Spawn # compression threads. [Default: 1; pass 0 for core count.]\n"); + DISPLAYOUT(" --single-thread Share a single thread for I/O and compression (slightly different than `-T1`).\n"); + DISPLAYOUT(" --auto-threads={physical|logical}\n"); + DISPLAYOUT(" Use physical/logical cores when using `-T0`. [Default: Physical]\n\n"); + DISPLAYOUT(" -B# Set job size to #. [Default: 0 (automatic)]\n"); + DISPLAYOUT(" --rsyncable Compress using a rsync-friendly method (`-B` sets block size). \n"); + DISPLAYOUT("\n"); # endif - DISPLAYOUT(" --exclude-compressed : only compress files that are not already compressed \n"); - DISPLAYOUT(" --stream-size=# specify size of streaming input from `stdin` \n"); - DISPLAYOUT(" --size-hint=# optimize compression parameters for streaming input of approximately this size \n"); - DISPLAYOUT(" --target-compressed-block-size=# : generate compressed block of approximately targeted size \n"); - DISPLAYOUT(" --no-dictID don't write dictID into header (dictionary compression only)\n"); - DISPLAYOUT(" --[no-]compress-literals : force (un)compressed literals\n"); - DISPLAYOUT(" --[no-]row-match-finder : force enable/disable usage of fast row-based matchfinder for greedy, lazy, and lazy2 strategies\n"); + DISPLAYOUT(" --exclude-compressed Only compress files that are not already compressed.\n\n"); - DISPLAYOUT(" --format=zstd compress files to the .zst format (default)\n"); + DISPLAYOUT(" --stream-size=# Specify size of streaming input from STDIN.\n"); + DISPLAYOUT(" --size-hint=# Optimize compression parameters for streaming input of approximately size #.\n"); + DISPLAYOUT(" --target-compressed-block-size=#\n"); + DISPLAYOUT(" Generate compressed blocks of approximately # size.\n\n"); + DISPLAYOUT(" --no-dictID Don't write `dictID` into the header (dictionary compression only).\n"); + DISPLAYOUT(" --[no-]compress-literals Force (un)compressed literals.\n"); + DISPLAYOUT(" --[no-]row-match-finder Explicitly enable/disable the fast, row-based matchfinder for\n"); + DISPLAYOUT(" the 'greedy', 'lazy', and 'lazy2' strategies.\n"); + + DISPLAYOUT("\n"); + DISPLAYOUT(" --format=zstd Compress files to the `.zst` format. [Default]\n"); #ifdef ZSTD_GZCOMPRESS - DISPLAYOUT(" --format=gzip compress files to the .gz format\n"); + DISPLAYOUT(" --format=gzip Compress files to the `.gz` format.\n"); #endif #ifdef ZSTD_LZMACOMPRESS - DISPLAYOUT(" --format=xz compress files to the .xz format\n"); - DISPLAYOUT(" --format=lzma compress files to the .lzma format\n"); + DISPLAYOUT(" --format=xz Compress files to the `.xz` format.\n"); + DISPLAYOUT(" --format=lzma Compress files to the `.lzma` format.\n"); #endif #ifdef ZSTD_LZ4COMPRESS - DISPLAYOUT( " --format=lz4 compress files to the .lz4 format\n"); + DISPLAYOUT( " --format=lz4 Compress files to the `.lz4` format.\n"); #endif #endif /* !ZSTD_NOCOMPRESS */ #ifndef ZSTD_NODECOMPRESS DISPLAYOUT("\n"); - DISPLAYOUT("Advanced decompression options :\n"); - DISPLAYOUT(" -l print information about zstd compressed files\n"); - DISPLAYOUT(" --test test compressed file integrity\n"); - DISPLAYOUT(" -M# Set a memory usage limit for decompression\n"); + DISPLAYOUT("Advanced decompression options:\n"); + DISPLAYOUT(" -l Print information about Zstandard-compressed files.\n"); + DISPLAYOUT(" --test Test compressed file integrity.\n"); + DISPLAYOUT(" -M# Set the memory usage limit to # megabytes.\n"); # if ZSTD_SPARSE_DEFAULT - DISPLAYOUT(" --[no-]sparse sparse mode (default: enabled on file, disabled on stdout)\n"); + DISPLAYOUT(" --[no-]sparse Enable sparse mode. [Default: Enabled for files, disabled for STDOUT.]\n"); # else - DISPLAYOUT(" --[no-]sparse sparse mode (default: disabled)\n"); + DISPLAYOUT(" --[no-]sparse Enable sparse mode. [Default: Disabled]\n"); # endif { - char const* passThroughDefault = "disabled"; + char const* passThroughDefault = "Disabled"; if (exeNameMatch(programName, ZSTD_CAT) || exeNameMatch(programName, ZSTD_ZCAT) || exeNameMatch(programName, ZSTD_GZCAT)) { - passThroughDefault = "enabled"; + passThroughDefault = "Enabled"; } - DISPLAYOUT(" --[no-]pass-through : passes through uncompressed files as-is (default: %s)\n", passThroughDefault); + DISPLAYOUT(" --[no-]pass-through Pass through uncompressed files as-is. [Default: %s]\n", passThroughDefault); } #endif /* ZSTD_NODECOMPRESS */ #ifndef ZSTD_NODICT DISPLAYOUT("\n"); - DISPLAYOUT("Dictionary builder :\n"); - DISPLAYOUT(" --train ## create a dictionary from a training set of files\n"); - DISPLAYOUT(" --train-cover[=k=#,d=#,steps=#,split=#,shrink[=#]] : use the cover algorithm with optional args\n"); - DISPLAYOUT(" --train-fastcover[=k=#,d=#,f=#,steps=#,split=#,accel=#,shrink[=#]] : use the fast cover algorithm with optional args\n"); - DISPLAYOUT(" --train-legacy[=s=#] : use the legacy algorithm with selectivity (default: %u)\n", g_defaultSelectivityLevel); - DISPLAYOUT(" -o DICT DICT is dictionary name (default: %s)\n", g_defaultDictName); - DISPLAYOUT(" --maxdict=# limit dictionary to specified size (default: %u)\n", g_defaultMaxDictSize); - DISPLAYOUT(" --dictID=# force dictionary ID to specified value (default: random)\n"); + DISPLAYOUT("Dictionary builder:\n"); + DISPLAYOUT(" --train Create a dictionary from a training set of files.\n\n"); + DISPLAYOUT(" --train-cover[=k=#,d=#,steps=#,split=#,shrink[=#]]\n"); + DISPLAYOUT(" Use the cover algorithm (with optional arguments).\n"); + DISPLAYOUT(" --train-fastcover[=k=#,d=#,f=#,steps=#,split=#,accel=#,shrink[=#]]\n"); + DISPLAYOUT(" Use the fast cover algorithm (with optional arguments).\n\n"); + DISPLAYOUT(" --train-legacy[=s=#] Use the legacy algorithm with selectivity #. [Default: %u]\n", g_defaultSelectivityLevel); + DISPLAYOUT(" -o NAME Use NAME as dictionary name. [Default: %s]\n", g_defaultDictName); + DISPLAYOUT(" --maxdict=# Limit dictionary to specified size #. [Default: %u]\n", g_defaultMaxDictSize); + DISPLAYOUT(" --dictID=# Force dictionary ID to #. [Default: Random]\n"); #endif #ifndef ZSTD_NOBENCH DISPLAYOUT("\n"); - DISPLAYOUT("Benchmark options : \n"); - DISPLAYOUT(" -b# benchmark file(s), using # compression level (default: %d)\n", ZSTDCLI_CLEVEL_DEFAULT); - DISPLAYOUT(" -e# test all compression levels successively from -b# to -e# (default: 1)\n"); - DISPLAYOUT(" -i# minimum evaluation time in seconds (default: 3s)\n"); - DISPLAYOUT(" -B# cut file into independent chunks of size # (default: no chunking)\n"); - DISPLAYOUT(" -S output one benchmark result per input file (default: consolidated result)\n"); - DISPLAYOUT(" --priority=rt set process priority to real-time\n"); + DISPLAYOUT("Benchmark options:\n"); + DISPLAYOUT(" -b# Perform benchmarking with compression level #. [Default: %d]\n", ZSTDCLI_CLEVEL_DEFAULT); + DISPLAYOUT(" -e# Test all compression levels up to #; starting level is `-b#`. [Default: 1]\n"); + DISPLAYOUT(" -i# Set the minimum evaluation to time # seconds. [Default: 3]\n"); + DISPLAYOUT(" -B# Cut file into independent chunks of size #. [Default: No chunking]\n"); + DISPLAYOUT(" -S Output one benchmark result per input file. [Default: Consolidated result]\n"); + DISPLAYOUT(" --priority=rt Set process priority to real-time.\n"); #endif } diff --git a/tests/cli-tests/basic/help.sh.stdout.glob b/tests/cli-tests/basic/help.sh.stdout.glob index bfb0f7753..5580dc669 100644 --- a/tests/cli-tests/basic/help.sh.stdout.glob +++ b/tests/cli-tests/basic/help.sh.stdout.glob @@ -1,25 +1,34 @@ + zstd -h -Usage: zstd *OPTION*... *FILE*... *-o file* -Compress or uncompress FILEs (with no FILE or when FILE is `-`, read from standard input). +Compress or decompress the INPUT file(s); reads from STDIN if INPUT is `-` or not provided. - -o file result stored into `file` (only 1 output file) - -1 .. -19 compression level (faster .. better; default: 3) - -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. 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 - -h display usage and exit - -H,--help display long help and exit +Usage: zstd *OPTIONS...* *INPUT... | -* *-o OUTPUT* + +Options: + -o OUTPUT Write output to a single file, OUTPUT. + -k, --keep Preserve INPUT file(s). *Default* + --rm Remove INPUT file(s) after successful (de)compression. + + -# Desired compression level, where `#` is a number between 1 and 19; + lower numbers provide faster compression, higher numbers yield + better compression ratios. *Default: 3* + + -d, --decompress Perform decompression. + -D DICT Use DICT as the dictionary for compression or decompression. + + -f, --force Disable input and output checks. Allows overwriting existing files, + receiving input from the console, printing ouput to STDOUT, and + operating on links, block devices, etc. Unrecognized formats will be + passed-through through as-is. + + -h Display short usage and exit. + -H, --help Display full help and exit. + -V, --version Display the program version and exit. + zstd -H ... -Advanced options : +Advanced options: ... + zstd --help ... -Advanced options : +Advanced options: ... diff --git a/tests/cli-tests/basic/version.sh.stdout.glob b/tests/cli-tests/basic/version.sh.stdout.glob index 54968fa41..4cc9fb9b2 100644 --- a/tests/cli-tests/basic/version.sh.stdout.glob +++ b/tests/cli-tests/basic/version.sh.stdout.glob @@ -1,2 +1,2 @@ -*** zstd command line interface *-bits v1.*.*, by Yann Collet *** -*** zstd command line interface *-bits v1.*.*, by Yann Collet *** +*** Zstandard CLI (*-bit) v1.*.*, by Yann Collet *** +*** Zstandard CLI (*-bit) v1.*.*, by Yann Collet *** diff --git a/tests/cli-tests/progress/no-progress.sh.stderr.glob b/tests/cli-tests/progress/no-progress.sh.stderr.glob index f07ad3803..b4262517a 100644 --- a/tests/cli-tests/progress/no-progress.sh.stderr.glob +++ b/tests/cli-tests/progress/no-progress.sh.stderr.glob @@ -55,36 +55,36 @@ decompress 2 files args = --no-progress --fake-stderr-is-console -v compress file to file -*zstd* +*Zstandard CLI* hello*hello.zst* compress pipe to pipe -*zstd* +*Zstandard CLI* *stdin*stdout* compress pipe to file -*zstd* +*Zstandard CLI* *stdin*hello.zst* compress file to pipe -*zstd* +*Zstandard CLI* *hello*stdout* compress 2 files -*zstd* +*Zstandard CLI* *hello*hello.zst* *world*world.zst* 2 files compressed* decompress file to file -*zstd* +*Zstandard CLI* hello.zst* decompress pipe to pipe -*zstd* +*Zstandard CLI* *stdin* decompress pipe to file -*zstd* +*Zstandard CLI* *stdin* decompress file to pipe -*zstd* +*Zstandard CLI* hello.zst* decompress 2 files -*zstd* +*Zstandard CLI* hello.zst* world.zst* 2 files decompressed*