cosmopolitan/third_party/lz4cli/README

LZ4(1)                Cosmopolitan User Commands               -*-text-*-

𝐍𝐀𝐌𝐄
       𝗹𝘇𝟰 - lz4, unlz4, lz4cat - Compress or decompress .lz4 files

𝐒𝐘𝐍𝐎𝐏𝐒𝐈𝐒
       𝗹𝘇𝟰 [O̲P̲T̲I̲O̲N̲S̲] [-|INPUT-FILE] O̲U̲T̲P̲U̲T̲-̲F̲I̲L̲E̲

       𝘂𝗻𝗹𝘇𝟰 is equivalent to 𝗹𝘇𝟰 -𝗱

       𝗹𝘇𝟰𝗰𝗮𝘁 is equivalent to 𝗹𝘇𝟰 -𝗱𝗰𝗳𝗺

       When  writing scripts that need to decompress files, it is recom‐
       mended to always use the name 𝗹𝘇𝟰 with appropriate arguments (𝗹𝘇𝟰
       -𝗱 or 𝗹𝘇𝟰 -𝗱𝗰) instead of the names 𝘂𝗻𝗹𝘇𝟰 and 𝗹𝘇𝟰𝗰𝗮𝘁.

𝐃𝐄𝐒𝐂𝐑𝐈𝐏𝐓𝐈𝐎𝐍
       𝗹𝘇𝟰 is an extremely fast lossless compression algorithm, based on
       𝗯𝘆𝘁𝗲-𝗮𝗹𝗶𝗴𝗻𝗲𝗱 𝐋𝐙𝟳𝟳 family of compression scheme. 𝗹𝘇𝟰  offers  com‐
       pression  speeds  of  400  MB/s  per core, linearly scalable with
       multi-core CPUs. It features  an  extremely  fast  decoder,  with
       speed  in  multiple  GB/s  per core, typically reaching RAM speed
       limit on multi-core systems. The native file format is  the  .𝗹𝘇𝟰
       format.

   𝐃𝗶𝗳𝗳𝗲𝗿𝗲𝗻𝗰𝗲 𝗯𝗲𝘁𝘄𝗲𝗲𝗻 𝗹𝘇𝟰 𝗮𝗻𝗱 𝗴𝘇𝗶𝗽
       𝗹𝘇𝟰  supports  a command line syntax similar b̲u̲t̲ n̲o̲t̲ i̲d̲e̲n̲t̲i̲c̲a̲l̲ to
       𝗴𝘇𝗶𝗽(𝟭). Differences are :

       ·   𝗹𝘇𝟰 preserves original files

       ·   𝗹𝘇𝟰 compresses a single file by default (see -𝗺 for  multiple
           files)

       ·   𝗹𝘇𝟰 𝗳𝗶𝗹𝗲𝟭 𝗳𝗶𝗹𝗲𝟮 means : compress file1 i̲n̲t̲o̲ file2

       ·   𝗹𝘇𝟰  𝗳𝗶𝗹𝗲.𝗹𝘇𝟰  will default to decompression (use -𝘇 to force
           compression)

       ·   𝗹𝘇𝟰 shows real-time notification statistics  during  compres‐
           sion  or  decompression  of  a single file (use -𝗾 to silence
           them)

       ·   If no destination name is provided, result is sent to  𝘀𝘁𝗱𝗼𝘂𝘁
           e̲x̲c̲e̲p̲t̲ i̲f̲ s̲t̲d̲o̲u̲t̲ i̲s̲ t̲h̲e̲ c̲o̲n̲s̲o̲l̲e̲.

       ·   If no destination name is provided, 𝗮𝗻𝗱 if 𝘀𝘁𝗱𝗼𝘂𝘁 is the con‐
           sole, 𝗳𝗶𝗹𝗲 is compressed into 𝗳𝗶𝗹𝗲.𝗹𝘇𝟰.

       ·   As a consequence of previous rules, note the following  exam‐
           ple  :  𝗹𝘇𝟰 𝗳𝗶𝗹𝗲 | 𝗰𝗼𝗻𝘀𝘂𝗺𝗲𝗿 sends compressed data to 𝗰𝗼𝗻𝘀𝘂𝗺𝗲𝗿
           through 𝘀𝘁𝗱𝗼𝘂𝘁, hence it does n̲o̲t̲ create 𝗳𝗶𝗹𝗲.𝗹𝘇𝟰.

       ·   Another consequence of those rules is that to run  𝗹𝘇𝟰  under
           𝗻𝗼𝗵𝘂𝗽,  you should provide a destination file: 𝗻𝗼𝗵𝘂𝗽 𝗹𝘇𝟰 𝗳𝗶𝗹𝗲
           𝗳𝗶𝗹𝗲.𝗹𝘇𝟰, because 𝗻𝗼𝗵𝘂𝗽 writes the specified command´s output
           to a file.



       Default  behaviors  can  be modified by opt-in commands, detailed
       below.

       ·   𝗹𝘇𝟰 -𝗺 makes it possible to provide multiple input filenames,
           which  will  be  compressed  into  files  using  suffix .𝗹𝘇𝟰.
           Progress notifications are also disabled by default  (use  -𝘃
           to  enable them). This mode has a behavior which more closely
           mimics 𝗴𝘇𝗶𝗽 command line, with the main remaining  difference
           being that source files are preserved by default.

       ·   Similarly, 𝗹𝘇𝟰 -𝗺 -𝗱 can decompress multiple *.𝗹𝘇𝟰 files.

       ·   It´s  possible  to opt-in to erase source files on successful
           compression or decompression, using --𝗿𝗺 command.

       ·   Consequently, 𝗹𝘇𝟰 -𝗺 --𝗿𝗺 behaves the same as 𝗴𝘇𝗶𝗽.



   𝐂𝗼𝗻𝗰𝗮𝘁𝗲𝗻𝗮𝘁𝗶𝗼𝗻 𝗼𝗳 .𝗹𝘇𝟰 𝗳𝗶𝗹𝗲𝘀
       It is possible to concatenate .𝗹𝘇𝟰 files as is. 𝗹𝘇𝟰  will  decom‐
       press such files as if they were a single .𝗹𝘇𝟰 file. For example:



           lz4 file1  > foo.lz4
           lz4 file2 >> foo.lz4



       Then 𝗹𝘇𝟰𝗰𝗮𝘁 𝗳𝗼𝗼.𝗹𝘇𝟰 is equivalent to 𝗰𝗮𝘁 𝗳𝗶𝗹𝗲𝟭 𝗳𝗶𝗹𝗲𝟮.

𝐎𝐏𝐓𝐈𝐎𝐍𝐒
   𝐒𝗵𝗼𝗿𝘁 𝗰𝗼𝗺𝗺𝗮𝗻𝗱𝘀 𝗰𝗼𝗻𝗰𝗮𝘁𝗲𝗻𝗮𝘁𝗶𝗼𝗻
       In  some cases, some options can be expressed using short command
       -𝘅 or long command --𝗹𝗼𝗻𝗴-𝘄𝗼𝗿𝗱. Short commands  can  be  concate‐
       nated  together.  For  example,  -𝗱 -𝗰 is equivalent to -𝗱𝗰. Long
       commands cannot be concatenated. They must be  clearly  separated
       by a space.

   𝐌𝘂𝗹𝘁𝗶𝗽𝗹𝗲 𝗰𝗼𝗺𝗺𝗮𝗻𝗱𝘀
       When multiple contradictory commands are issued on a same command
       line, only the latest one will be applied.

   𝐎𝗽𝗲𝗿𝗮𝘁𝗶𝗼𝗻 𝗺𝗼𝗱𝗲
       -𝘇 --𝗰𝗼𝗺𝗽𝗿𝗲𝘀𝘀
              Compress. This is the default operation mode when no oper‐
              ation mode option is specified, no other operation mode is
              implied from the command name (for example, 𝘂𝗻𝗹𝘇𝟰  implies
              --𝗱𝗲𝗰𝗼𝗺𝗽𝗿𝗲𝘀𝘀),  nor from the input file name (for example,
              a file extension .𝗹𝘇𝟰 implies --𝗱𝗲𝗰𝗼𝗺𝗽𝗿𝗲𝘀𝘀 by default). -𝘇
              can  also  be used to force compression of an already com‐
              pressed .𝗹𝘇𝟰 file.

       -𝗱 --𝗱𝗲𝗰𝗼𝗺𝗽𝗿𝗲𝘀𝘀 --𝘂𝗻𝗰𝗼𝗺𝗽𝗿𝗲𝘀𝘀
              Decompress. --𝗱𝗲𝗰𝗼𝗺𝗽𝗿𝗲𝘀𝘀 is  also  the  default  operation
              when the input filename has an .𝗹𝘇𝟰 extension.

       -𝘁 --𝘁𝗲𝘀𝘁
              Test  the  integrity  of compressed .𝗹𝘇𝟰 files. The decom‐
              pressed data  is  discarded.  No  files  are  created  nor
              removed.

       -𝗯#    Benchmark mode, using # compression level.

   𝐎𝗽𝗲𝗿𝗮𝘁𝗶𝗼𝗻 𝗺𝗼𝗱𝗶𝗳𝗶𝗲𝗿𝘀
       -#     Compression  level,  with  # being any value from 1 to 12.
              Higher values  trade  compression  speed  for  compression
              ratio. Values above 12 are considered the same as 12. Rec‐
              ommended values are 1 for fast compression (default),  and
              9  for  high compression. Speed/compression trade-off will
              vary depending on data to  compress.  Decompression  speed
              remains fast at all settings.

       -𝐃 𝗱𝗶𝗰𝘁𝗶𝗼𝗻𝗮𝗿𝘆𝐍𝗮𝗺𝗲
              Compress, decompress or benchmark using dictionary d̲i̲c̲t̲i̲o̲‐̲
              n̲a̲r̲y̲N̲a̲m̲e̲. Compression and decompression must use the  same
              dictionary  to be compatible. Using a different dictionary
              during decompression will either abort due  to  decompres‐
              sion error, or generate a checksum error.

       -𝗳 --[𝗻𝗼-]𝗳𝗼𝗿𝗰𝗲
              This option has several effects:

              If  the  target  file already exists, overwrite it without
              prompting.

              When used with --𝗱𝗲𝗰𝗼𝗺𝗽𝗿𝗲𝘀𝘀 and 𝗹𝘇𝟰 cannot  recognize  the
              type  of  the  source  file, copy the source file as is to
              standard output. This allows 𝗹𝘇𝟰𝗰𝗮𝘁  --𝗳𝗼𝗿𝗰𝗲  to  be  used
              like  𝗰𝗮𝘁 (𝟭) for files that have not been compressed with
              𝗹𝘇𝟰.

       -𝗰 --𝘀𝘁𝗱𝗼𝘂𝘁 --𝘁𝗼-𝘀𝘁𝗱𝗼𝘂𝘁
              Force write to standard output, even if it is the console.

       -𝗺 --𝗺𝘂𝗹𝘁𝗶𝗽𝗹𝗲
              Multiple  input  files.  Compressed  file  names  will  be
              appended  a  .𝗹𝘇𝟰 suffix. This mode also reduces notifica‐
              tion level. 𝗹𝘇𝟰 -𝗺 has a behavior equivalent  to  𝗴𝘇𝗶𝗽  -𝗸
              (it preserves source files by default).

       -𝗿     operate recursively on directories. This mode also sets -𝗺
              (multiple input files).

       -𝐁#    Block size [4-7](default : 7)
              -𝐁𝟰= 64KB ; -𝐁𝟱= 256KB ; -𝐁𝟲= 1MB ; -𝐁𝟳= 4MB

       -𝐁𝐃    Block Dependency  (improves  compression  ratio  on  small
              blocks)

       --𝗳𝗮𝘀𝘁[=#]
              switch  to  ultra-fast  compression  levels.  If =# is not
              present, it defaults to  𝟭.  The  higher  the  value,  the
              faster the compression speed, at the cost of some compres‐
              sion ratio. This setting overwrites compression  level  if
              one  was set previously. Similarly, if a compression level
              is set after --𝗳𝗮𝘀𝘁, it overrides it.

       --[𝗻𝗼-]𝗳𝗿𝗮𝗺𝗲-𝗰𝗿𝗰
              Select frame checksum (default:enabled)

       --[𝗻𝗼-]𝗰𝗼𝗻𝘁𝗲𝗻𝘁-𝘀𝗶𝘇𝗲
              Header includes original size (default:not present)
              Note : this option can only be activated when the original
              size  can  be  determined, hence for a file. It won´t work
              with unknown source size, such as stdin or pipe.

       --[𝗻𝗼-]𝘀𝗽𝗮𝗿𝘀𝗲
              Sparse mode support (default:enabled on file, disabled  on
              stdout)

       -𝗹     Use Legacy format (typically for Linux Kernel compression)
              Note : -𝗹 is not compatible with -𝗺 (--𝗺𝘂𝗹𝘁𝗶𝗽𝗹𝗲) nor -𝗿

   𝐎𝘁𝗵𝗲𝗿 𝗼𝗽𝘁𝗶𝗼𝗻𝘀
       -𝘃 --𝘃𝗲𝗿𝗯𝗼𝘀𝗲
              Verbose mode

       -𝗾 --𝗾𝘂𝗶𝗲𝘁
              Suppress  warnings and real-time statistics; specify twice
              to suppress errors too

       -𝗵 -𝐇 --𝗵𝗲𝗹𝗽
              Display help/long help and exit

       -𝐕 --𝘃𝗲𝗿𝘀𝗶𝗼𝗻
              Display Version number and exit

       -𝗸 --𝗸𝗲𝗲𝗽
              Preserve source files (default behavior)

       --𝗿𝗺   Delete source files on successful  compression  or  decom‐
              pression

       --     Treat all subsequent arguments as files

   𝐁𝗲𝗻𝗰𝗵𝗺𝗮𝗿𝗸 𝗺𝗼𝗱𝗲
       -𝗯#    Benchmark file(s), using # compression level

       -𝗲#    Benchmark  multiple  compression  levels,  from  b#  to e#
              (included)

       -𝗶#    Minimum evaluation time in seconds [1-9] (default : 3)

𝐁𝐔𝐆𝐒
       Report bugs at: https://github.com/lz4/lz4/issues

𝐀𝐔𝐓𝐇𝐎𝐑
       Yann Collet

lz4 1.8.3                       September 2018                          LZ4(1)