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. Automatic formats detection.
  28 3. Same usage syntax for all formats.
  29 4. Uses encoding and decoding streams to improve performance.
  30 5. No runtime dependencies (for _Linux x86_64_).
  31 6. Can list archive contents with pretty tree formatting.
  32 7. Shell completions (soon!).
  33
  34 # Usage
  35
  36 ## Decompressing
  37
  38 Use the `decompress` subcommand and pass the files.
  39
  40 ```sh
  41 # Decompress a file
  42 ouch decompress a.zip
  43
  44 # Decompress multiple files
  45 ouch decompress a.zip b.tar.gz c.tar
  46
  47 # Short alternative
  48 ouch d a.zip
  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 Use the `compress` subcommand, pass the files and the **output file** at the end.
  61
  62 ```sh
  63 # Compress four files
  64 ouch compress 1 2 3 4 archive.zip
  65
  66 # Short alternative
  67 ouch c file.txt file.zip
  68 ```
  69
  70 `ouch` detects the extensions of the **output file** to decide what formats to use.
  71
  72 # Supported formats
  73
  74 | Format    | `.tar` | `.zip` | `.bz`, `.bz2` | `.gz` | `.lz4` | `.xz`, `.lzma` | `.zst` |
  75 |:---------:|:------:|:------:|:-------------:|:-----:|:------:|:---------------------:|:------:|
  76 | Supported | ✓     | ✓      | ✓            | ✓     | ✓     | ✓                     | ✓     |
  77
  78 And the aliases: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlz`, `tlzma`, `tzst`.
  79
  80 Formats can be chained:
  81
  82 - `.tar.gz`
  83 - `.tar.gz.gz.gz.gz`
  84 - `.tar.gz.gz.gz.gz.zst.xz.bz.lz4`
  85
  86 # Installation
  87
  88 [![Packaging status](https://repology.org/badge/vertical-allrepos/ouch.svg)](https://repology.org/project/ouch/versions)
  89
  90 ## Downloading the latest binary
  91
  92 Compiled for `x86_64` on _Linux_, _Mac OS_ and _Windows_, run with `curl` or `wget`.
  93
  94 | Method    | Command                                                                             |
  95 |:---------:|:------------------------------------------------------------------------------------|
  96 | **curl**  | `curl -s https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh \| sh`   |
  97 | **wget**  | `wget https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh -O - \| sh` |
  98
  99 The script will copy the [latest binary](https://github.com/ouch-org/ouch/releases) to `/usr/local/bin`.
 100
 101 ## Compiling from source code
 102
 103 Check the [wiki guide](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
 104
 105 # Dependencies
 106
 107 If you installed `ouch` using the download script, you will need no dependencies (static MUSL binary).
 108
 109 Otherwise, you'll need these libraries installed on your system:
 110
 111 * [liblzma](https://www.7-zip.org/sdk.html)
 112 * [libbz2](https://www.sourceware.org/bzip2/)
 113 * [libz](https://www.zlib.net/)
 114
 115 These are available on all mainstream _Linux_ distributions and on _macOS_.
 116
 117 # Benchmarks
 118
 119 Comparison made decompressing `linux.tar.gz` and measured with
 120 [Hyperfine](https://github.com/sharkdp/hyperfine) and the values presented are the average (wall clock) elapsed time.
 121
 122 | Tool         | `ouch` | [`tar`] | [`bsdtar`] |
 123 |:------------:|:------:|:-------:|:----------:|
 124 | Average time | 911 ms | 1102 ms |   829 ms   |
 125
 126 Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
 127 we plan on doing some optimization in the future.
 128
 129 Versions used:
 130
 131 - `ouch` _0.3.1_
 132 - [`tar`] _1.34_
 133 - [`bsdtar`] _3.5.2_
 134
 135 # Contributing
 136
 137 `ouch` is made out of voluntary work, contributors are very welcome! No contribution is too small and all contributions are valued.
 138
 139 - Open an [issue](https://github.com/ouch-org/ouch/issues).
 140 - Package it for your favorite distribution or package manager.
 141 - Open a pull request.
 142 - Share it with a friend!
 143
 144 [`tar`]: https://www.gnu.org/software/tar/
 145 [`bsdtar`]: https://www.freebsd.org/cgi/man.cgi?query=bsdtar&sektion=1&format=html