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 pacman -S ouch
 127 ```
 128
 129 ## On Windows via Scoop
 130
 131 ```cmd
 132 scoop install ouch
 133 ```
 134
 135 ## From crates.io
 136
 137 ```bash
 138 cargo install ouch
 139 ```
 140
 141 ## Download the latest release bundle
 142
 143 Check the [releases page](https://github.com/ouch-org/ouch/releases).
 144
 145 ## Compiling from source code
 146
 147 Check the [wiki guide on compiling](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
 148
 149 # Dependencies
 150
 151 If you installed `ouch` using the download script, you will need no dependencies (static MUSL binary).
 152
 153 Otherwise, you'll need these libraries installed on your system:
 154
 155 * [liblzma](https://www.7-zip.org/sdk.html)
 156 * [libbz2](https://www.sourceware.org/bzip2/)
 157 * [libz](https://www.zlib.net/)
 158
 159 These are available on all mainstream _Linux_ distributions and on _macOS_.
 160
 161 # Benchmarks
 162
 163 Benchmark results are available [here](benchmarks/results.md).
 164 Performance of compressing and decompressing
 165 [Rust](https://github.com/rust-lang/rust) source code are measured and compared with
 166 [Hyperfine](https://github.com/sharkdp/hyperfine).
 167 The values presented are the average (wall clock) elapsed time.
 168
 169 Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
 170 we plan on doing some optimization in the future.
 171
 172 Versions used:
 173
 174 - `ouch` _0.4.0_
 175 - [`tar`] _1.34_
 176 - [`unzip`][infozip] _6.00_
 177 - [`zip`][infozip] _3.0_
 178
 179 # Contributing
 180
 181 `ouch` is made out of voluntary work, contributors are very welcome! No contribution is too small and all contributions are valued.
 182
 183 - Open an [issue](https://github.com/ouch-org/ouch/issues).
 184 - Package it for your favorite distribution or package manager.
 185 - Open a pull request.
 186 - Share it with a friend!
 187
 188 [`tar`]: https://www.gnu.org/software/tar/
 189 [infozip]: http://www.info-zip.org/