From abf1d4e3e40e9064c7a184883fb3478c440c6c08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Marcos=20Bezerra?= Date: Sat, 6 Nov 2021 02:29:56 -0300 Subject: [PATCH] Readme update (#161) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Updating badges * Reformatted support table to be monospaced * Add first benchmark to the readme And fixed a typo * Some readme rewording * Removing readme redundant compression example * Change badges to have squared corners * readme: increase headers size by one * Slight modifications to the README * Specify dependencies and tweak some other stuff * Add MSRV Co-authored-by: Vinícius Miguel <36349314+vrmiguel@users.noreply.github.com> --- README.md | 137 ++++++++++++++++++++++++++++++++---------------- src/commands.rs | 2 +- 2 files changed, 92 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 15b0b46..db053b2 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,60 @@ +

+ + Crates.io link + + + Docs.rs link + + + License + +

+ # Ouch! -[![crates.io](https://img.shields.io/crates/v/ouch.svg?style=for-the-badge&logo=rust)](https://crates.io/crates/ouch) [![license](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge&logo=Open-Source-Initiative&logoColor=ffffff)](https://github.com/ouch-org/ouch/blob/main/LICENSE) - -`ouch` stands for **Obvious Unified Compression Helper**, it's a CLI tool to compress and decompress files. +`ouch` stands for **Obvious Unified Compression Helper** and is a CLI tool to help you compress and decompress files of several formats. - [Features](#features) - [Usage](#usage) - [Installation](#installation) - [Supported Formats](#supported-formats) +- [Benchmarks](#benchmarks) - [Contributing](#contributing) -## Features +# Features 1. Easy to use. -2. Automatic format detection. -3. Same syntax, various formats. -4. Encoding and decoding streams, it's fast. +2. Infers expression formats automatically. +3. Uses the same usage syntax for all supported formats. +4. Achieves great performance through encoding and decoding streams. 5. No runtime dependencies (for _Linux x86_64_). 6. Listing archive contents with tree formatting (in next release!). -## Usage +# Usage -### Decompressing +## Decompressing Use the `decompress` subcommand and pass the files. ```sh -# Decompress one +# Decompress a file ouch decompress a.zip -# Decompress multiple +# Decompress multiple files ouch decompress a.zip b.tar.gz c.tar # Short alternative ouch d a.zip ``` -You can redirect the decompression results to another folder with the `-d/--dir` flag. +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 -d pictures +ouch decompress summer_vacation.zip --dir pictures ``` -### Compressing +## Compressing Use the `compress` subcommand, pass the files and the **output file** at the end. @@ -53,38 +64,15 @@ ouch compress 1 2 3 4 archive.zip # Short alternative ouch c file.txt file.zip - -# Compress everything in the current folder again and again -ouch compress * everything.tar.gz.xz.bz.zst.gz.gz.gz.gz.gz ``` -`ouch` checks for the extensions of the **output file** to decide which formats should be used. +`ouch` detects the extensions of the **output file** to decide what formats to use. -## Installation +# Supported formats -[![Packaging status](https://repology.org/badge/vertical-allrepos/ouch.svg)](https://repology.org/project/ouch/versions) - -### Downloading the latest binary - -Compiled for `x86_64` on _Linux_, _Mac OS_ and _Windows_, run with `curl` or `wget`. - -| Method | Command | -|:---------:|:-----------------------------------------------------------------------------------| -| **curl** | `curl -s https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh \| sh` | -| **wget** | `wget https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh -O - \| sh` | - - -The script will download the [latest binary](https://github.com/ouch-org/ouch/releases) and copy it to `/usr/bin`. - -### Installing from source code - -For compiling, check the [wiki guide](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code). - -## Supported formats - -| Format | .tar | .zip | .bz, .bz2 | .gz | .lz4 | .xz, .lz, .lzma | .zst | -|:-------------:|:----:|:----:|:---------:|:---:|:----:|:---------------:|:----:| -| Supported | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +| Format | `.tar` | `.zip` | `.bz`, `.bz2` | `.gz` | `.lz4` | `.xz`, `.lz`, `.lzma` | `.zst` | +|:---------:|:------:|:------:|:-------------:|:-----:|:------:|:---------------------:|:------:| +| Supported | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | And the aliases: `tgz`, `tbz`, `tbz2`, `tlz4`, `txz`, `tlz`, `tlzma`, `tzst`. @@ -94,10 +82,67 @@ Formats can be chained (`ouch` keeps it _fast_): - `.tar.gz.xz.bz.zst` - `.tar.gz.gz.gz.gz.xz.xz.xz.xz.bz.bz.bz.bz.zst.zst.zst.zst` -## Contributing +# Installation -`ouch` is 100% made out of voluntary work, any small contribution is welcome! +[![Packaging status](https://repology.org/badge/vertical-allrepos/ouch.svg)](https://repology.org/project/ouch/versions) -- Open an issue. +## Downloading the latest binary + +Compiled for `x86_64` on _Linux_, _Mac OS_ and _Windows_, run with `curl` or `wget`. + +| Method | Command | +|:---------:|:------------------------------------------------------------------------------------| +| **curl** | `curl -s https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh \| sh` | +| **wget** | `wget https://raw.githubusercontent.com/ouch-org/ouch/master/install.sh -O - \| sh` | + +The script will copy the [latest binary](https://github.com/ouch-org/ouch/releases) to `/usr/local/bin`. + +## Minimum Supported Rust Version + +`ouch` will always be developed with the latest stable release of the Rust toolchain. + +## Installing from source code + +Check the [wiki guide](https://github.com/ouch-org/ouch/wiki/Compiling-and-installing-from-source-code). + +# Dependencies + +When built dynamically linked, you'll need these libraries to be available on your system: + +* [liblzma](https://www.7-zip.org/sdk.html) +* [libbz2](https://www.sourceware.org/bzip2/) +* [libz](https://www.zlib.net/) + +Thankfully these are all very common libraries that _should_ already be available on all mainstream Linux distributions and on macOS. + +`ouch` is also easily built with MUSL, in which case it's _statically linked_ and therefore has no runtime dependencies. + +# Benchmarks + +Comparison made decompressing `linux.tar.gz` and measured with +[Hyperfine](https://github.com/sharkdp/hyperfine) and the values presented are the average (wall clock) elapsed time. + +| Tool | `ouch` | [`tar`] | [`bsdtar`] | +|:------------:|:------:|:-------:|:----------:| +| Average time | 911 ms | 1102 ms | 829 ms | + +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.3.1_ +- [`tar`] _1.34_ +- [`bsdtar`] _3.5.2_ + +# Contributing + +`ouch` is made out of voluntary work, contributors are very welcome! No contribution is too small and all contributions are valued. + +- Open an [issue](https://github.com/ouch-org/ouch/issues). +- Package it for your favorite distribution or package manager. - Open a pull request. -- Share it to a friend! +- Share it with a friend! + +[`tar`]: https://www.gnu.org/software/tar/ +[`bsdtar`]: https://www.freebsd.org/cgi/man.cgi?query=bsdtar&sektion=1&format=html diff --git a/src/commands.rs b/src/commands.rs index 3103398..06f0736 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -130,7 +130,7 @@ pub fn run(args: Opts, question_policy: QuestionPolicy) -> crate::Result<()> { // Note: If input_extensions is empty then it will make `formats` empty too, which we don't want if !input_extensions.is_empty() && new_formats != formats { // Safety: - // We checked above that input_extensions isn't empty, so files[0] has a extension. + // We checked above that input_extensions isn't empty, so files[0] has an extension. // // Path::extension says: "if there is no file_name, then there is no extension". // Using DeMorgan's law: "if there is extension, then there is file_name".