summaryrefslogtreecommitdiffstats
path: root/modules/brotli/tools/brotli.md
blob: c029869bced73a478e68a63b21369eedc4bd6634 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
brotli(1) -- brotli, unbrotli - compress or decompress files
================================================================

SYNOPSIS
--------

`brotli` [*OPTION|FILE*]...

`unbrotli` is equivalent to `brotli --decompress`

DESCRIPTION
-----------
`brotli` is a generic-purpose lossless compression algorithm that compresses
data using a combination of a modern variant of the **LZ77** algorithm, Huffman
coding and 2-nd order context modeling, with a compression ratio comparable to
the best currently available general-purpose compression methods. It is similar
in speed with deflate but offers more dense compression.

`brotli` command line syntax similar to `gzip (1)` and `zstd (1)`.
Unlike `gzip (1)`, source files are preserved by default. It is possible to
remove them after processing by using the `--rm` _option_.

Arguments that look like "`--name`" or "`--name=value`" are _options_. Every
_option_ has a short form "`-x`" or "`-x value`". Multiple short form _options_
could be coalesced:

* "`--decompress --stdout --suffix=.b`" works the same as
* "`-d -s -S .b`" and
* "`-dsS .b`"

`brotli` has 3 operation modes:

* default mode is compression;
* `--decompress` option activates decompression mode;
* `--test` option switches to integrity test mode; this option is equivalent to
  "`--decompress --stdout`" except that the decompressed data is discarded
  instead of being written to standard output.

Every non-option argument is a _file_ entry. If no _files_ are given or _file_
is "`-`", `brotli` reads from standard input. All arguments after "`--`" are
_file_ entries.

Unless `--stdout` or `--output` is specified, _files_ are written to a new file
whose name is derived from the source _file_ name:

* when compressing, a suffix is appended to the source filename to
  get the target filename
* when decompressing, a suffix is removed from the source filename to
  get the target filename

Default suffix is `.br`, but it could be specified with `--suffix` option.

Conflicting or duplicate _options_ are not allowed.

OPTIONS
-------

* `-#`:
    compression level (0-9); bigger values cause denser, but slower compression
* `-c`, `--stdout`:
    write on standard output
* `-d`, `--decompress`:
    decompress mode
* `-f`, `--force`:
    force output file overwrite
* `-h`, `--help`:
    display this help and exit
* `-j`, `--rm`:
    remove source file(s); `gzip (1)`-like behaviour
* `-k`, `--keep`:
    keep source file(s); `zstd (1)`-like behaviour
* `-n`, `--no-copy-stat`:
    do not copy source file(s) attributes
* `-o FILE`, `--output=FILE`
    output file; valid only if there is a single input entry
* `-q NUM`, `--quality=NUM`:
    compression level (0-11); bigger values cause denser, but slower compression
* `-t`, `--test`:
    test file integrity mode
* `-v`, `--verbose`:
    increase output verbosity
* `-w NUM`, `--lgwin=NUM`:
    set LZ77 window size (0, 10-24) (default: 22); window size is
    `(2**NUM - 16)`; 0 lets compressor decide over the optimal value; bigger
    windows size improve density; decoder might require up to window size
    memory to operate
* `-S SUF`, `--suffix=SUF`:
    output file suffix (default: `.br`)
* `-V`, `--version`:
    display version and exit
* `-Z`, `--best`:
    use best compression level (default); same as "`-q 11`"

SEE ALSO
--------

`brotli` file format is defined in
[RFC 7932](https://www.ietf.org/rfc/rfc7932.txt).

`brotli` is open-sourced under the
[MIT License](https://opensource.org/licenses/MIT).

Mailing list: https://groups.google.com/forum/#!forum/brotli

BUGS
----
Report bugs at: https://github.com/google/brotli/issues