README.md

   1 <p align="center">
   2   <a href="https://crates.io/crates/ouch">
   3     <img src="https://img.shields.io/crates/v/ouch?color=6090FF&style=flat-square" alt="Crates.io link">
   4   </a>
   5   <a href="https://github.com/ouch/ouch-org/blob/master/LICENSE">
   6     <img src="https://img.shields.io/crates/l/ouch?color=6090FF&style=flat-square" alt="License">
   7   </a>
   8 </p>
   9
  10 # Ouch!
  11
  12 `ouch` stands for **Obvious Unified Compression Helper**.
  13
  14 It's a CLI tool for compressing and decompressing for various formats.
  15
  16 - [Features](#features)
  17 - [Usage](#usage)
  18 - [Installation](#installation)
  19 - [Supported Formats](#supported-formats)
  20 - [Benchmarks](#benchmarks)
  21 - [Contributing](#contributing)
  22
  23 # Features
  24
  25 1. Easy to use.
  26 2. Fast.
  27 3. Great error message feedback.
  28 4. No runtime dependencies required (for _Linux x86_64_).
  29 5. Accessibility mode ([see more](https://github.com/ouch-org/ouch/wiki/Accessibility)).
  30 6. Shell completions and man pages.
  31
  32 # Usage
  33
  34 Ouch has three main subcommands:
  35
  36 - `ouch decompress` (alias `d`)
  37 - `ouch compress` (alias `c`)
  38 - `ouch list` (alias `l` or `ls`)
  39
  40 To see `help` for a specific command:
  41
  42 ```sh
  43 ouch help <COMMAND>
  44 ouch <COMMAND> --help  # equivalent
  45 ```
  46
  47 ## Decompressing
  48
  49 Use the `decompress` subcommand, `ouch` will detect the extensions automatically.
  50
  51 ```sh
  52 ouch decompress a.zip
  53
  54 # Decompress multiple files
  55 ouch decompress a.zip b.tar.gz c.tar
  56 ```
  57
  58 The `-d/--dir` flag can be used to redirect decompression results to another directory.
  59
  60 ```sh
  61 # Decompress 'summer_vacation.zip' inside of new folder 'pictures'
  62 ouch decompress summer_vacation.zip --dir pictures
  63 ```
  64
  65 ## Compressing
  66
  67 Pass input files to the `compress` subcommand, add the **output file** at the end.
  68
  69 ```sh
  70 # Compress two files into `archive.zip`
  71 ouch compress one.txt two.txt archive.zip
  72
  73 # Compress file.txt using .lz4 and .zst
  74 ouch compress file.txt file.txt.lz4.zst
  75 ```
  76
  77 `ouch` detects the extensions of the **output file** to decide what formats to use.
  78
  79 ## Listing
  80
  81 ```sh
  82 ouch list archive.zip
  83
  84 # Example with tree formatting
  85 ouch list source-code.zip --tree
  86 ```
  87
  88 Output:
  89
  90 ```
  91 └── src
  92    ├── archive
  93    │  ├── mod.rs
  94    │  ├── tar.rs
  95    │  └── zip.rs
  96    ├── utils
  97    │  ├── colors.rs
  98    │  ├── formatting.rs
  99    │  ├── mod.rs
 100    │  └── fs.rs
 101    ├── commands
 102    │  ├── list.rs
 103    │  ├── compress.rs
 104    │  ├── decompress.rs
 105    │  └── mod.rs
 106    ├── accessible.rs
 107    ├── error.rs
 108    ├── cli.rs
 109    └── main.rs
 110 ```
 111
 112 # Supported formats
 113
 114 | Format    | `.tar` | `.zip` | `.gz` | `.xz`, `.lzma` | `.bz`, `.bz2` | `.lz4` | `.sz` | `.zst` |
 115 |:---------:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 116 | Supported | ✓ | ✓¹ | ✓² | ✓ | ✓ | ✓ | ✓² | ✓ |
 117
 118 ✓: Supports compression and decompression.
 119
 120 ✓¹: Due to limitations of `.zip`, it doesn't support streaming (de)compression.
 121
 122 ✓²: Supported, and compression runs in parallel.
 123
 124 `tar` aliases are also supported: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlzma`, `tsz`, `tzst`.
 125
 126 Formats can be chained:
 127
 128 - `.zst.gz`
 129 - `.tar.gz.gz`
 130 - `.tar.gz.gz.gz.zst.xz.bz.lz4`
 131
 132 If the filename has no extensions, `Ouch` will try to infer the format by the [file signature](https://en.wikipedia.org/wiki/List_of_file_signatures).
 133
 134 # Installation
 135
 136 <a href="https://repology.org/project/ouch/versions">
 137   <img align="right" src="https://repology.org/badge/vertical-allrepos/ouch.svg" alt="Packaging status" />
 138 </a>
 139
 140 ## On Arch Linux
 141
 142 ```bash
 143 pacman -S ouch
 144 ```
 145
 146 ## On Windows via Scoop
 147
 148 ```cmd
 149 scoop install ouch
 150 ```
 151
 152 ## From crates.io
 153
 154 ```bash
 155 cargo install ouch
 156 ```
 157
 158 ## Download the latest release bundle
 159
 160 Check the [releases page](https://github.com/ouch-org/ouch/releases).
 161
 162 ## Compiling from source code
 163
 164 Check the [wiki guide on compiling](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
 165
 166 # Dependencies
 167
 168 If you installed `ouch` using the download script, you will need no dependencies (static MUSL binary).
 169
 170 Otherwise, you'll need these libraries installed on your system:
 171
 172 * [liblzma](https://www.7-zip.org/sdk.html)
 173 * [libbz2](https://www.sourceware.org/bzip2/)
 174 * [libz](https://www.zlib.net/)
 175
 176 These are available on all mainstream _Linux_ distributions and on _macOS_.
 177
 178 # Benchmarks
 179
 180 Benchmark results are available [here](benchmarks/results.md).
 181 Performance of compressing and decompressing
 182 [Rust](https://github.com/rust-lang/rust) source code are measured and compared with
 183 [Hyperfine](https://github.com/sharkdp/hyperfine).
 184 The values presented are the average (wall clock) elapsed time.
 185
 186 Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
 187 we plan on doing some optimization in the future.
 188
 189 Versions used:
 190
 191 - `ouch` _0.4.0_
 192 - [`tar`] _1.34_
 193 - [`unzip`][infozip] _6.00_
 194 - [`zip`][infozip] _3.0_
 195
 196 # Contributing
 197
 198 `ouch` is made out of voluntary work, contributors are very welcome! No contribution is too small and all contributions are valued.
 199
 200 - Open an [issue](https://github.com/ouch-org/ouch/issues).
 201 - Package it for your favorite distribution or package manager.
 202 - Open a pull request.
 203 - Share it with a friend!
 204
 205 [`tar`]: https://www.gnu.org/software/tar/
 206 [infozip]: http://www.info-zip.org/