
lzma command line tool README
-----------------------------

    Copyright (C) 2007 Lasse Collin

    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.


Overview

    The lzma command line tool is similar to gzip and bzip2, but for
    compressing and uncompressing .lzma files.


Supported file formats

    By default, the tool creates files in the new .lzma format. This can
    be overriden with --format=FMT command line option. Use --format=alone
    to create files in the old LZMA_Alone format.

    By default, the tool uncompresses both the new .lzma format and
    LZMA_Alone format. This is to make it transparent to switch from
    the old LZMA_Alone format to the new .lzma format. Since both
    formats use the same filename suffix, average user should never
    notice which format was used.


Differences to gzip and bzip2

  Standard input and output

    Both gzip and bzip2 refuse to write compressed data to a terminal and
    read compressed data from a terminal. With gzip (but not with bzip2),
    this can be overriden with the `--force' option. lzma follows the
    behavior of gzip here.

  Usage of LZMA_OPT environment variable

    gzip and bzip2 read GZIP and BZIP2 environment variables at startup.
    These variables may contain extra command line options.

    gzip and bzip2 allow passing not only options, but also end-of-options
    indicator (`--') and filenames via the environment variable. No quoting
    is supported with the filenames.

    Here are examples with gzip. bzip2 behaves identically.

        bash$ echo asdf > 'foo bar'
        bash$ GZIP='"foo bar"' gzip
        gzip: "foo: No such file or directory
        gzip: bar": No such file or directory

        bash$ GZIP=-- gzip --help
        gzip: --help: No such file or directory

    lzma silently ignores all non-option arguments given via the
    environment variable LZMA_OPT. Like on the command line, everything
    after `--' is taken as non-options, and thus ignored in LZMA_OPT.

        bash$ LZMA_OPT='--help' lzma --version     # Displays help
        bash$ LZMA_OPT='-- --help' lzma --version  # Displays version


History

    The first version of LZMA Utils (4.27.0) included a shell script
    called `lzmash'. It was wrapper that had gzip-like command line
    interface. It used the LZMA_Alone tool from LZMA SDK to do all
    the real work.

    The `lzmash' script was an ugly and not very secure hack. In LZMA
    Utils 4.32.0betas the script got replaced with a real tool written
    in C++. It used the encoder and decoder from C++ LZMA SDK with very
    little modifications. The new lzma tool never got some features like
    support for LZMA_OPT environment variable, which was the reason why
    it was never offically called stable.

    LZMA Utils 4.42.0alphas introduced third revision of the gzip-like
    lzma command line tool. It uses liblzma to do the actual compression.
    This new command line tool introduces several new features compared
    to LZMA Utils 4.32.0betas:
      - support for the new .lzma file format
      - multiple filters to provide even higher compression ratio
      - multi-threading
      - memory usage control
      - uncompressing of concatenated .lzma files
      - viewing information about files with `lzma --list'
      - LZMA_OPT environment variable
      - native language support (NLS)

    The development of LZMA Utils 4.42.x is still in alpha stage. Several
    features are still missing or don't fully work yet.

