From 3f47d2f6d69b0dbbdd576e67e667b467f4db038b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Marcos=20Bezerra?= Date: Tue, 30 Mar 2021 22:34:21 -0300 Subject: [PATCH] Update README.md --- README.md | 156 ++++++++++++++++++++++++------------------------------ 1 file changed, 69 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index 6a00e55..f31efb3 100644 --- a/README.md +++ b/README.md @@ -1,133 +1,115 @@ -# ouch (_work in progress_) +# Ouch! -`ouch` is the Obvious Unified Compression (_and decompression_) Helper. +### This readme is a WIP draft, and does not represent the reality +See the old README at https://github.com/vrmiguel/ouch/tree/0f453e9dfc70066056b9cc40e8032dcc6ee703bc + + +`ouch` loosely stands for Obvious Unified Compression (ᵃⁿᵈ ᵈᵉᶜᵒᵐᵖʳᵉˢˢᶦᵒⁿ) Helper and aims to be an easy and intuitive way of compressing and decompressing files on the command-line. + +- [Usage](#Usage) + - [Decompress](#Decompress) + - [Compress](#Compress) + - [Convert](#Convert) +- [Supported Formats](#Supported-formats) +- [Installation](#Installation) +- [Supported operating systems](#Supported-operating-systems) -| Supported formats | .tar | .zip | .tar.{.lz*,.gz, .bz} | .zip.{.lz*, .gz, .bz*} | .bz | .gz | .lz, .lzma | -|-------------------|------|------|------------------------------|------------------------------|-----|-----|------------| -| Decompression | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Compression | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | +## Usage -## How does it work? +`ouch` uses the file extensions to infer the file formats. -`ouch` infers commands from the extensions of its command-line options. +For example, `ouch compress a b c.zip` tells to compress `a` and `b` into the same `c.zip` compressed file. -``` -ouch 0.1.4 -Vinícius R. Miguel -ouch is a unified compression & decompression utility +### Decompressing files + -USAGE: - ouch [OPTIONS] --input ... +To decompress, just call `ouch` passing the input files. -FLAGS: - -h, --help Displays this message and exits - -V, --version Prints version information - -OPTIONS: - -i, --input ... The input files or directories. - -o, --output The output directory or compressed file. -``` - -### Examples - -#### Decompressing a bunch of files +Use the `-o, --output` flag to redirect the output to a folder. ```bash -$ ouch -i file{1..5}.zip another_file.tar.gz yet_another_file.tar.bz +# Decompress `a.zip` +ouch a.zip + +# Decompress multiple files +ouch a.zip b.tar.gz + +# Decompress multiple files, but inside new_folder +ouch a.zip b.tar.gz -o new_folder ``` -When no output file is supplied, `ouch` infers that it must decompress all of its input files into the current folder. This will error if any of the input files are not decompressible. +### Compressing files and directories -#### Decompressing a bunch of files into a folder +The `compress` subcommand accepts files and folders where the **last** one is the desired **output file**. ```bash -$ ouch -i file{1..3}.tar.gz videos.tar.bz2 -o some-folder -# Decompresses file1.tar.gz, file2.tar.gz, file3.tar.gz and videos.tar.bz2 to some-folder -# The folder `ouch` saves to will be created if it doesn't already exist +# Compress four files into `archive.zip` +ouch compress a b c d archive.zip + +# Compress three files into `.tar.bz2` archive +ouch compress a.mp4 b.jpg c.png files.tar.bz2 + +# Compress a folder and a file into `videos.tar.xz` +ouch compress Videos/ funny_meme.mp4 videos.tar.xz ``` -When the output file is not a compressed file, `ouch` will check if all input files are decompressible and infer that it must decompress them into the output folder. +### Converting between compressed archives -#### Compressing files - -```bash -$ ouch -i file{1..20} -o archive.tar -$ ouch -i Videos/ Movies/ -o media.tar.lzma -$ ouch -i src/ Cargo.toml Cargo.lock -o my_project.tar.gz +``` +# Will decompress a.tar.gz b.tar.bz and compress it into new-archive.tar.xz2 +ouch convert a.tar.gz b.tar.bz new-archive.tar.xz2 ``` -### Error scenarios +### Listing the elements of an archive -#### No clear decompression algorithm +(TODO -- not implemented at all) -```bash -$ ouch -i some-file -o some-folder -error: file 'some-file' is not decompressible. +``` +# Shows the files contained in videos.tar.xz +ouch list videos.tar.xz +1. ..... ``` -`ouch` cannot infer `some-file`'s compression format since it lacks an extension. Likewise, `ouch` cannot infer that the output file given is a compressed file, so it shows the user an error. +## Supported formats -```bash -$ ouch -i file other-file -o files.gz -error: cannot compress multiple files directly to Gzip. - Try using an intermediate archival method such as Tar. - Example: filename.tar.gz + +| | .tar | .zip | .tar.\*¹ | .zip.\*² | .bz, .bz2 | .gz | .xz, .lz, .lzma | .7z | +|:-------------:|:----:|:----:|:--------:|:--------:|:---------:| --- |:---------------:| --- | +| Decompression | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | +| Compression | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | + +``` +Note: .tar.*¹: .tar.gz, .tar.bz, .tar.bz2, .tar.xz, .tar.lz, .tar.lzma, .tar.zip + .zip.*²: .zip.gz, .zip.bz, .zip.bz2, .zip.xz, .zip.lz, .zip.lzma, .zip.zip ``` -Similar errors are shown if the same scenario is applied to `.lz/.lzma` and `.bz/.bz2`. ## Installation -### Runtime dependencies +### Getting a pre-compiled binary -`ouch` depends on a few widespread libraries: -* libbz2 -* liblzma +```bash +curl -s https://raw.githubusercontent.com/vrmiguel/ouch/master/install.sh | bash +``` -Both should be already installed in any mainstream Linux distribution. +### Building -If they're not, then: +A recent [Rust] toolchain is needed to build `ouch`. Go to [rustup.rs](https://rustup.rs/) to get it. -* On Debian-based distros - -`sudo apt install liblzma-dev libbz2-dev` - -* On Arch-based distros - -`sudo pacman -S xz bzip2` - -The last dependency is a recent [Rust](https://www.rust-lang.org/) toolchain. If you don't have one installed, follow the instructions at [rustup.rs](https://rustup.rs/). - -### Build process - -Once the dependency requirements are met: - -* Installing from [Crates.io](https://crates.io) +Once [Cargo](https://doc.rust-lang.org/cargo/) is installed, run: ```bash cargo install ouch -``` - -* Cloning and building - -```bash +# or git clone https://github.com/vrmiguel/ouch cargo install --path ouch -# or -cd ouch && cargo run --release ``` -I also recommend stripping the release binary. `ouch`'s release binary (at the time of writing) only takes up a megabyte in space when stripped. - ## Supported operating systems -`ouch` _should_ be cross-platform but is currently only tested (and developed) on Linux, on both x64-64 and ARM. + ## Limitations -`ouch` does encoding and decoding in-memory, so decompressing very large files with `ouch` is not advisable. - -## Contributions - -Any contributions and suggestions are welcome! +`ouch` does encoding and decoding in-memory, so decompressing very large files with it is not advisable.