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 ## Decompressing
  41
  42 Use the `decompress` subcommand, `ouch` will detect the extensions automatically.
  43
  44 ```sh
  45 ouch decompress a.zip
  46
  47 # Decompress multiple files
  48 ouch decompress a.zip b.tar.gz c.tar
  49 ```
  50
  51 The `-d/--dir` flag can be used to redirect decompression results to another directory.
  52
  53 ```sh
  54 # Decompress 'summer_vacation.zip' inside of new folder 'pictures'
  55 ouch decompress summer_vacation.zip --dir pictures
  56 ```
  57
  58 ## Compressing
  59
  60 Pass input files to the `compress` subcommand, add the **output file** at the end.
  61
  62 ```sh
  63 # Compress two files into `archive.zip`
  64 ouch compress one.txt two.txt archive.zip
  65
  66 # Compress file.txt using .lz4 and .zst
  67 ouch compress file.txt file.txt.lz4.zst
  68 ```
  69
  70 `ouch` detects the extensions of the **output file** to decide what formats to use.
  71
  72 ## Listing
  73
  74 ```sh
  75 ouch list archive.zip
  76
  77 # Example with tree formatting
  78 ouch list source-code.zip --tree
  79 ```
  80
  81 Output:
  82
  83 ```
  84 └── src
  85    ├── archive
  86    │  ├── mod.rs
  87    │  ├── tar.rs
  88    │  └── zip.rs
  89    ├── utils
  90    │  ├── colors.rs
  91    │  ├── formatting.rs
  92    │  ├── mod.rs
  93    │  └── fs.rs
  94    ├── commands
  95    │  ├── list.rs
  96    │  ├── compress.rs
  97    │  ├── decompress.rs
  98    │  └── mod.rs
  99    ├── accessible.rs
 100    ├── error.rs
 101    ├── cli.rs
 102    └── main.rs
 103 ```
 104
 105 # Supported formats
 106
 107 | Format    | `.tar` | `.zip` | `.gz` | `.xz`, `.lzma` | `.bz`, `.bz2` | `.lz4` | `.sz` | `.zst` |
 108 |:---------:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 109 | Supported | ✓ | ✓¹ | ✓² | ✓ | ✓ | ✓ | ✓² | ✓ |
 110
 111 ✓: Supports compression and decompression.
 112
 113 ✓¹: Due to limitations of `.zip`, it doesn't support streaming (de)compression.
 114
 115 ✓²: Supported, and compression runs in parallel.
 116
 117 `tar` aliases are also supported: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlzma`, `tsz`, `tzst`.
 118
 119 Formats can be chained:
 120
 121 - `.zst.gz`
 122 - `.tar.gz.gz`
 123 - `.tar.gz.gz.gz.zst.xz.bz.lz4`
 124
 125 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).
 126
 127 # Installation
 128
 129 <a href="https://repology.org/project/ouch/versions">
 130   <img align="right" src="https://repology.org/badge/vertical-allrepos/ouch.svg" alt="Packaging status" />
 131 </a>
 132
 133 ## On Arch Linux
 134
 135 ```bash
 136 pacman -S ouch
 137 ```
 138
 139 ## On Windows via Scoop
 140
 141 ```cmd
 142 scoop install ouch
 143 ```
 144
 145 ## From crates.io
 146
 147 ```bash
 148 cargo install ouch
 149 ```
 150
 151 ## Download the latest release bundle
 152
 153 Check the [releases page](https://github.com/ouch-org/ouch/releases).
 154
 155 ## Compiling from source code
 156
 157 Check the [wiki guide on compiling](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
 158
 159 # Dependencies
 160
 161 If you installed `ouch` using the download script, you will need no dependencies (static MUSL binary).
 162
 163 Otherwise, you'll need these libraries installed on your system:
 164
 165 * [liblzma](https://www.7-zip.org/sdk.html)
 166 * [libbz2](https://www.sourceware.org/bzip2/)
 167 * [libz](https://www.zlib.net/)
 168
 169 These are available on all mainstream _Linux_ distributions and on _macOS_.
 170
 171 # Benchmarks
 172
 173 Benchmark results are available [here](benchmarks/results.md).
 174 Performance of compressing and decompressing
 175 [Rust](https://github.com/rust-lang/rust) source code are measured and compared with
 176 [Hyperfine](https://github.com/sharkdp/hyperfine).
 177 The values presented are the average (wall clock) elapsed time.
 178
 179 Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
 180 we plan on doing some optimization in the future.
 181
 182 Versions used:
 183
 184 - `ouch` _0.4.0_
 185 - [`tar`] _1.34_
 186 - [`unzip`][infozip] _6.00_
 187 - [`zip`][infozip] _3.0_
 188
 189 # Contributing
 190
 191 `ouch` is made out of voluntary work, contributors are very welcome! No contribution is too small and all contributions are valued.
 192
 193 - Open an [issue](https://github.com/ouch-org/ouch/issues).
 194 - Package it for your favorite distribution or package manager.
 195 - Open a pull request.
 196 - Share it with a friend!
 197
 198 [`tar`]: https://www.gnu.org/software/tar/
 199 [infozip]: http://www.info-zip.org/