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-org/ouch/blob/main/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` | `7z` | `.gz` | `.xz`, `.lzma` | `.bz`, `.bz2` | `.lz4` | `.sz` (Snappy) | `.zst` | `.rar` |
 115 |:---------:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 116 | Supported | ✓ | ✓¹ | ✓¹ | ✓² | ✓ | ✓ | ✓ | ✓² | ✓ | ✓³ |
 117
 118 ✓: Supports compression and decompression.
 119
 120 ✓¹: Due to limitations of the compression format itself, (de)compression can't be done with streaming.
 121
 122 ✓²: Supported, and compression runs in parallel.
 123
 124 ✓³: Due to RAR's restrictive license, only decompression and listing can be supported.
 125 If you wish to exclude non-free code from your build, you can disable RAR support
 126 by building without the `unrar` feature.
 127
 128 `tar` aliases are also supported: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlzma`, `tsz`, `tzst`.
 129
 130 Formats can be chained:
 131
 132 - `.tar.gz`
 133 - `.tar.gz.xz.zst.gz.lz4.sz`
 134
 135 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) and ask the user for confirmation.
 136
 137 # Installation
 138
 139 <a href="https://repology.org/project/ouch/versions">
 140   <img align="right" src="https://repology.org/badge/vertical-allrepos/ouch.svg" alt="Packaging status" />
 141 </a>
 142
 143 ## On Arch Linux
 144
 145 ```bash
 146 pacman -S ouch
 147 ```
 148
 149 ## On Windows via Scoop
 150
 151 ```cmd
 152 scoop install ouch
 153 ```
 154
 155 ## From crates.io
 156
 157 ```bash
 158 cargo install ouch
 159 ```
 160
 161 ## Download the latest release bundle
 162
 163 Check the [releases page](https://github.com/ouch-org/ouch/releases).
 164
 165 ## Compiling from source code
 166
 167 Check the [wiki guide on compiling](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
 168
 169 # Runtime Dependencies
 170
 171 If running `ouch` results in a linking error, it means you're missing a runtime dependency.
 172
 173 If you're downloading binaries from the [releases page](https://github.com/ouch-org/ouch/releases), try the `musl` variants, those are static binaries that require no runtime dependencies.
 174
 175 Otherwise, you'll need these libraries installed on your system:
 176
 177 * [liblzma](https://www.7-zip.org/sdk.html)
 178 * [libbz2](https://www.sourceware.org/bzip2)
 179 * [libz](https://www.zlib.net)
 180
 181 These should be available in your system's package manager.
 182
 183 # Benchmarks
 184
 185 Benchmark results are available [here](benchmarks/results.md).
 186 Performance of compressing and decompressing
 187 [Rust](https://github.com/rust-lang/rust) source code are measured and compared with
 188 [Hyperfine](https://github.com/sharkdp/hyperfine).
 189 The values presented are the average (wall clock) elapsed time.
 190
 191 Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
 192 we plan on doing some optimization in the future.
 193
 194 Versions used:
 195
 196 - `ouch` _0.4.0_
 197 - [`tar`] _1.34_
 198 - [`unzip`][infozip] _6.00_
 199 - [`zip`][infozip] _3.0_
 200
 201 # Contributing
 202
 203 `ouch` is made out of voluntary work, contributors are very welcome! Contributions of all sizes are appreciated.
 204
 205 - Open an [issue](https://github.com/ouch-org/ouch/issues).
 206 - Package it for your favorite distribution or package manager.
 207 - Share it with a friend!
 208 - Open a pull request.
 209
 210 If you're creating a Pull Request, check [CONTRIBUTING.md](./CONTRIBUTING.md).
 211
 212 [`tar`]: https://www.gnu.org/software/tar/
 213 [infozip]: http://www.info-zip.org/