ouch

Ouch!

ouch stands for Obvious Unified Compression Helper.

It's a CLI tool for compressing and decompressing various formats.

• Features
• Usage
• Installation
• Supported Formats
• Benchmarks
• Contributing

Features

1. Easy to use.
2. Fast.
3. Great error message feedback.
4. No runtime dependencies.
5. Accessibility mode (see more).
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:

ouch help <COMMAND>
ouch <COMMAND> --help  # equivalent

Decompressing

Use the decompress subcommand, ouch will detect the extensions automatically.

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.

# 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).

# 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.

# 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

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 and ask the user for confirmation.

Installation

Refer to the packages list on the right.

The most commonly used installation methods:

On Arch Linux

pacman -S ouch

On MacOS via Homebrew

brew install ouch

On Windows via Scoop

scoop install ouch

From crates.io

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 APT archive per its instructions (packages for Debian stable, testing and unstable, amd64 and arm64, built from source at release tags), then:

sudo apt install ouch

Download the latest release bundle

Check the releases page.

Release binaries are signed with Sigstore using cosign. Download the asset and its .sigstore.json bundle from the releases page, 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 <tag>
export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct)
export RUSTFLAGS="--remap-path-prefix=$(pwd)=."
cargo build --locked --release --target <triple>

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.

Benchmarks

Benchmark results are available here. Performance of compressing and decompressing Rust source code is measured and compared with 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 6.00
• zip 3.0

Contributing

Contributions of all sizes are welcome and appreciated!

• Open an issue.
• 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.