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`)
  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 And the aliases: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlzma`, `tsz`, `tzst`.
 112
 113 Formats can be chained:
 114
 115 - `.tar.gz`
 116 - `.tar.gz.gz.gz.gz`
 117 - `.tar.gz.gz.gz.gz.zst.xz.bz.lz4`
 118
 119 # Installation
 120
 121 [![Packaging status](https://repology.org/badge/vertical-allrepos/ouch.svg)](https://repology.org/project/ouch/versions)
 122
 123 ## On Arch Linux
 124
 125 ```bash
 126 yay -S ouch
 127 ```
 128
 129 ## From crates.io
 130
 131 ```bash
 132 cargo install ouch
 133 ```
 134
 135 ## Using our script to download the latest binary
 136
 137 Compiled for `x86_64` on _Linux_, _Mac OS_ and _Windows_, run with `curl` or `wget`.
 138
 139 | Method    | Command                                                                             |
 140 |:---------:|:------------------------------------------------------------------------------------|
 141 | **curl**  | `curl -s https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh \| sh`   |
 142 | **wget**  | `wget https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh -O - \| sh` |
 143
 144 The script will copy the [latest binary](https://github.com/ouch-org/ouch/releases) to `/usr/local/bin`.
 145
 146 ## Compiling from source code
 147
 148 Check the [wiki guide on compiling](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
 149
 150 # Dependencies
 151
 152 If you installed `ouch` using the download script, you will need no dependencies (static MUSL binary).
 153
 154 Otherwise, you'll need these libraries installed on your system:
 155
 156 * [liblzma](https://www.7-zip.org/sdk.html)
 157 * [libbz2](https://www.sourceware.org/bzip2/)
 158 * [libz](https://www.zlib.net/)
 159
 160 These are available on all mainstream _Linux_ distributions and on _macOS_.
 161
 162 # Benchmarks
 163
 164 Comparison made decompressing `linux.tar.gz` and measured with
 165 [Hyperfine](https://github.com/sharkdp/hyperfine) and the values presented are the average (wall clock) elapsed time.
 166
 167 | Tool         | `ouch` | [`tar`] | [`bsdtar`] |
 168 |:------------:|:------:|:-------:|:----------:|
 169 | Average time | 911 ms | 1102 ms |   829 ms   |
 170
 171 Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
 172 we plan on doing some optimization in the future.
 173
 174 Versions used:
 175
 176 - `ouch` _0.3.1_
 177 - [`tar`] _1.34_
 178 - [`bsdtar`] _3.5.2_
 179
 180 # Contributing
 181
 182 `ouch` is made out of voluntary work, contributors are very welcome! No contribution is too small and all contributions are valued.
 183
 184 - Open an [issue](https://github.com/ouch-org/ouch/issues).
 185 - Package it for your favorite distribution or package manager.
 186 - Open a pull request.
 187 - Share it with a friend!
 188
 189 [`tar`]: https://www.gnu.org/software/tar/
 190 [`bsdtar`]: https://www.freebsd.org/cgi/man.cgi?query=bsdtar&sektion=1&format=html