# Ouch!
`ouch` stands for **Obvious Unified Compression Helper**.
It's a CLI tool for compressing and decompressing various formats.
- [Features](#features)
- [Usage](#usage)
- [Installation](#installation)
- [Supported Formats](#supported-formats)
- [Benchmarks](#benchmarks)
- [Contributing](#contributing)
# Features
1. Easy to use.
2. Fast.
3. Great error message feedback.
4. No runtime dependencies.
5. Accessibility mode ([see more](https://github.com/ouch-org/ouch/wiki/Accessibility)).
6. Shell completions and man pages.
7. Decompression from standard input.
# Usage
`ouch` has three main subcommands:
- `ouch decompress` (alias `d`)
- `ouch compress` (alias `c`)
- `ouch list` (alias `l` or `ls`)
To see `help` for a specific command:
```sh
ouch help
ouch --help # equivalent
```
## Decompressing
Use the `decompress` subcommand, `ouch` will detect the extensions automatically.
```sh
ouch decompress a.zip
# Decompress multiple files
ouch decompress a.zip b.tar.gz c.tar
```
The `-d/--dir` flag can be used to redirect decompression results to another directory.
```sh
# Decompress 'summer_vacation.zip' inside of new folder 'pictures'
ouch decompress summer_vacation.zip --dir pictures
```
Files can also be decompressed from STDIN by passing `-` as the input path and
providing the format with `-f/--format` (there is no path to infer the format from).
```sh
# Decompress archive read from STDIN, writing contents to `ouch-output`
cat a.tar.gz | ouch decompress - --format tar.gz
```
## Compressing
Pass input files to the `compress` subcommand, add the **output file** at the end.
```sh
# Compress two files into `archive.zip`
ouch compress one.txt two.txt archive.zip
# Compress file.txt using .lz4 and .zst
ouch compress file.txt file.txt.lz4.zst
```
`ouch` detects the extensions of the **output file** to decide what formats to use.
## Listing
```sh
ouch list archive.zip
# Example with tree formatting
ouch list source-code.zip --tree
# Show the (uncompressed) size of each file
ouch list archive.zip --show-size
```
Output:
```
└── src
├── archive
│ ├── mod.rs
│ ├── tar.rs
│ └── zip.rs
├── utils
│ ├── colors.rs
│ ├── formatting.rs
│ ├── mod.rs
│ └── fs.rs
├── commands
│ ├── list.rs
│ ├── compress.rs
│ ├── decompress.rs
│ └── mod.rs
├── accessible.rs
├── error.rs
├── cli.rs
└── main.rs
```
# Supported formats
| Format | `.tar` | `.zip` | `.7z` | `.gz` | `.sz` | `.zst` | `.xz` | `.lzma` | `.lz` | `.bz`, `.bz2` | `.bz3` | `.lz4` | `.rar` | `.br` |
|:---------:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| Supported | ✓ | ✓¹ | ✓¹ | ✓² | ✓² | ✓² | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓³ | ✓ |
✓: Supports compression and decompression.
✓¹: Due to limitations of the compression format itself, (de)compression can't be done with streaming.
✓²: Supported, and compression runs in parallel.
✓³: Due to RAR's restrictive license, only decompression and listing can be supported.
If you wish to exclude non-free code from your build, you can disable RAR support
by building without the `unrar` feature.
Aliases for these formats are also supported:
- `tar`: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlzma`, `tsz`, `tzst`, `tlz`, `cbt`
- `zip`: `cbz`, `epub`
- `7z`: `cb7`
- `rar`: `cbr`
Formats can be chained:
- `.tar.gz`
- `.tar.gz.xz.zst.gz.lz4.sz`
If the filename has no extensions, `ouch` will try to infer the format by the [file signature](https://en.wikipedia.org/wiki/List_of_file_signatures) and ask the user for confirmation.
# Installation
Refer to the packages list on the right.
The most commonly used installation methods:
## On Arch Linux
```bash
pacman -S ouch
```
## On MacOS via Homebrew
```bash
brew install ouch
```
## On Windows via Scoop
```cmd
scoop install ouch
```
## From crates.io
```bash
cargo install ouch
```
(If you're on Ubuntu, you might need to install `clang` to build it from crates.io.)
## On Debian via pkg.haus
Set up the [pkg.haus](https://pkg.haus) APT archive per its instructions (packages for Debian stable, testing and unstable, amd64 and arm64, built from source at release tags), then:
```bash
sudo apt install ouch
```
## Download the latest release bundle
Check the [releases page](https://github.com/ouch-org/ouch/releases).
Release binaries are signed with [Sigstore](https://sigstore.dev) using [`cosign`](https://github.com/sigstore/cosign). Download the asset and its `.sigstore.json` bundle from the [releases page](https://github.com/ouch-org/ouch/releases), then verify:
```
cosign verify-blob ouch-x86_64-unknown-linux-musl.tar.gz --bundle ouch-x86_64-unknown-linux-musl.tar.gz.sigstore.json --certificate-identity-regexp='^https://github.com/ouch-org/ouch/' --certificate-oidc-issuer=https://token.actions.githubusercontent.com
```
### Reproducing a release build
Release builds are reproducible. Given the source at a tagged commit, anyone can rebuild the same binary and check that it matches what we shipped. Steps:
```
git clone https://github.com/ouch-org/ouch
cd ouch
git checkout
export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
export RUSTFLAGS="--remap-path-prefix=$(pwd)=."
cargo build --locked --release --target
```
The toolchain version is pinned in `rust-toolchain.toml` and rustup will install it automatically. Cross-compiled targets (anything using `cross-rs/cross`) inherit the cross Docker image's toolchain, which is not pinned by digest yet, so those targets are bit-for-bit reproducible only against the same `cross` image release.
## Compiling from source code
Check the [wiki guide on compiling](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code).
# Benchmarks
Benchmark results are available [here](benchmarks/results.md).
Performance of compressing and decompressing
[Rust](https://github.com/rust-lang/rust) source code is measured and compared with
[Hyperfine](https://github.com/sharkdp/hyperfine).
The values presented are the average (wall clock) elapsed time.
Note: `ouch` focuses heavily on usage ergonomics and nice error messages, but
we plan on doing some optimization in the future.
Versions used:
- `ouch` _0.4.0_
- [`tar`] _1.34_
- [`unzip`][infozip] _6.00_
- [`zip`][infozip] _3.0_
# Contributing
Contributions of all sizes are welcome and appreciated!
- Open an [issue](https://github.com/ouch-org/ouch/issues).
- Package it for your favorite distribution or package manager.
- Share it with a friend!
- Open a pull request.
If you're creating a Pull Request, check [CONTRIBUTING.md](./CONTRIBUTING.md).
[`tar`]: https://www.gnu.org/software/tar/
[infozip]: http://www.info-zip.org/