README.md

   1 # ouch (_work in progress_)
   2
   3 `ouch` is the Obvious Unified Compression (and decompression) Helper.
   4
   5
   6 | Supported formats | .tar | .zip | .tar.{.lz*,.gz, .bz}         | .zip.{.lz*, .gz, .bz*}       | .bz | .gz | .lz, .lzma |
   7 |-------------------|------|------|------------------------------|------------------------------|-----|-----|------------|
   8 | Decompression     |   ✓  |   ✓  |               ✓              |               ✓              |  ✓  |  ✓  |      ✓     |
   9 | Compression       |   ✓  |   ✓  |               ✓              |               ✓              |  ✓  |  ✓  |      ✓     |
  10
  11 ## How does it work?
  12
  13 `ouch` infers commands from the extensions of its command-line options.
  14
  15 ```
  16 ouch 0.1.2
  17 Vinícius R. Miguel
  18 ouch is a unified compression & decompression utility
  19
  20 USAGE:
  21     ouch [OPTIONS] --input <input>...
  22
  23 FLAGS:
  24     -h, --help       Displays this message and exits
  25     -V, --version    Prints version information
  26
  27 OPTIONS:
  28     -i, --input <input>...    The input files or directories.
  29     -o, --output <output>     The output directory or compressed file.
  30 ```
  31
  32 ### Examples
  33
  34 #### Decompressing a bunch of files
  35
  36 ```bash
  37 $ ouch -i file{1..5}.zip another_file.tar.gz yet_another_file.tar.bz
  38 ```
  39
  40 When no output file is supplied, `ouch` infers that it must decompress all of its input files. This will error if any of the input files are not decompressible.
  41
  42 #### Decompressing a bunch of files into a folder
  43
  44 ```bash
  45 $ ouch -i file{1..5}.tar.gz -o some-folder
  46 # Decompresses file1.tar.gz, file2.tar.gz, file3.tar.gz, file4.tar.gz and file5.tar.gz to some-folder
  47 # The folder `ouch` saves to will be created if it doesn't already exist
  48 ```
  49
  50 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 file.
  51
  52 #### Compressing files
  53
  54 ```bash
  55 $ ouch -i file{1..20} -o archive.tar
  56 ```
  57
  58 ### Error scenarios
  59
  60 #### No clear decompression algorithm
  61
  62 ```bash
  63 $ ouch -i some-file -o some-folder
  64 error: file 'some-file' is not decompressible.
  65 ```
  66
  67 `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.
  68
  69 ## Installation
  70
  71 ### Runtime dependencies
  72
  73 `ouch` depends on a few widespread libraries:
  74 * libbz2
  75 * liblzma
  76
  77 Both should be already installed in any mainstream Linux distribution.
  78
  79 If they're not, then:
  80
  81 * On Debian-based distros
  82
  83 `sudo apt install liblzma-dev libbz2-dev`
  84
  85 * On Arch-based distros
  86
  87 `sudo pacman -S xz bzip2`
  88
  89 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/).
  90
  91 ### Build process
  92
  93 Once the dependency requirements are met:
  94
  95 * Installing from [Crates.io](https://crates.io)
  96
  97 ```bash
  98 cargo install ouch
  99 ```
 100
 101 * Cloning and building
 102
 103 ```bash
 104 git clone https://github.com/vrmiguel/ouch
 105 cargo install --path ouch
 106 # or
 107 cd ouch && cargo run --release
 108 ```
 109
 110 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.