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