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://docs.rs/ouch">
   6     <img src="https://img.shields.io/docsrs/ouch?color=6090FF&style=flat-square" alt="Docs.rs link">
   7   </a>
   8   <a href="https://github.com/ouch/ouch-org/blob/master/LICENSE">
   9     <img src="https://img.shields.io/crates/l/ouch?color=6090FF&style=flat-square" alt="License">
  10   </a>
  11 </p>
  12
  13 # Ouch!
  14
  15 `ouch` stands for **Obvious Unified Compression Helper** and is a CLI tool to help you compress and decompress files of several formats.
  16
  17 - [Features](#features)
  18 - [Usage](#usage)
  19 - [Installation](#installation)
  20 - [Supported Formats](#supported-formats)
  21 - [Benchmarks](#benchmarks)
  22 - [Contributing](#contributing)
  23
  24 # Features
  25
  26 1. Easy to use.
  27 2. Accessibility mode (A11Y) via `--accessibility` or `ACCESSIBILITY` env var (see [wiki page](https://github.com/ouch-org/ouch/wiki/Accessibility)).
  28 3. Automatic formats detection.
  29 4. Same usage syntax for all formats.
  30 5. Uses encoding and decoding streams to improve performance.
  31 6. No runtime dependencies (for _Linux x86_64_).
  32 7. Can list archive contents with pretty tree formatting.
  33 8. Shell completions (soon!).
  34
  35 # Usage
  36
  37 ## Decompressing
  38
  39 Use the `decompress` subcommand and pass the files.
  40
  41 ```sh
  42 # Decompress a file
  43 ouch decompress a.zip
  44
  45 # Decompress multiple files
  46 ouch decompress a.zip b.tar.gz c.tar
  47
  48 # Short alternative
  49 ouch d a.zip
  50 ```
  51
  52 The `-d/--dir` flag can be used to redirect decompression results to another directory.
  53
  54 ```sh
  55 # Decompress 'summer_vacation.zip' inside of new folder 'pictures'
  56 ouch decompress summer_vacation.zip --dir pictures
  57 ```
  58
  59 ## Compressing
  60
  61 Use the `compress` subcommand, pass the files and the **output file** at the end.
  62
  63 ```sh
  64 # Compress four files
  65 ouch compress 1 2 3 4 archive.zip
  66
  67 # Short alternative
  68 ouch c file.txt file.zip
  69 ```
  70
  71 `ouch` detects the extensions of the **output file** to decide what formats to use.
  72
  73 # Supported formats
  74
  75 | Format    | `.tar` | `.zip` | `.bz`, `.bz2` | `.gz` | `.lz4` | `.xz`, `.lzma` | `.sz` | `.zst` |
  76 |:---------:|:------:|:------:|:-------------:|:-----:|:------:|:--------------:|:-----:|:-------|
  77 | Supported | ✓      | ✓      | ✓             | ✓     | ✓      | ✓              | ✓     | ✓      |
  78
  79 And the aliases: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlzma`, `tsz`, `tzst`.
  80
  81 Formats can be chained:
  82
  83 - `.tar.gz`
  84 - `.tar.gz.gz.gz.gz`
  85 - `.tar.gz.gz.gz.gz.zst.xz.bz.lz4`
  86
  87 # Installation
  88
  89 [![Packaging status](https://repology.org/badge/vertical-allrepos/ouch.svg)](https://repology.org/project/ouch/versions)
  90
  91 ## Downloading the latest binary
  92
  93 Compiled for `x86_64` on _Linux_, _Mac OS_ and _Windows_, run with `curl` or `wget`.
  94
  95 | Method    | Command                                                                             |
  96 |:---------:|:------------------------------------------------------------------------------------|
  97 | **curl**  | `curl -s https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh \| sh`   |
  98 | **wget**  | `wget https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh -O - \| sh` |
  99
 100 The script will copy the [latest binary](https://github.com/ouch-org/ouch/releases) to `/usr/local/bin`.
 101
 102 ## Compiling from source code
 103
 104 Check the [wiki guide](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
 105
 106 # Dependencies
 107
 108 If you installed `ouch` using the download script, you will need no dependencies (static MUSL binary).
 109
 110 Otherwise, you'll need these libraries installed on your system:
 111
 112 * [liblzma](https://www.7-zip.org/sdk.html)
 113 * [libbz2](https://www.sourceware.org/bzip2/)
 114 * [libz](https://www.zlib.net/)
 115
 116 These are available on all mainstream _Linux_ distributions and on _macOS_.
 117
 118 # Benchmarks
 119
 120 Comparison made decompressing `linux.tar.gz` and measured with
 121 [Hyperfine](https://github.com/sharkdp/hyperfine) and the values presented are the average (wall clock) elapsed time.
 122
 123 | Tool         | `ouch` | [`tar`] | [`bsdtar`] |
 124 |:------------:|:------:|:-------:|:----------:|
 125 | Average time | 911 ms | 1102 ms |   829 ms   |
 126
 127 Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
 128 we plan on doing some optimization in the future.
 129
 130 Versions used:
 131
 132 - `ouch` _0.3.1_
 133 - [`tar`] _1.34_
 134 - [`bsdtar`] _3.5.2_
 135
 136 # Contributing
 137
 138 `ouch` is made out of voluntary work, contributors are very welcome! No contribution is too small and all contributions are valued.
 139
 140 - Open an [issue](https://github.com/ouch-org/ouch/issues).
 141 - Package it for your favorite distribution or package manager.
 142 - Open a pull request.
 143 - Share it with a friend!
 144
 145 [`tar`]: https://www.gnu.org/software/tar/
 146 [`bsdtar`]: https://www.freebsd.org/cgi/man.cgi?query=bsdtar&sektion=1&format=html