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.3
  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 into the current folder. 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..3}.tar.gz videos.tar.bz2 -o some-folder
  46 # Decompresses file1.tar.gz, file2.tar.gz, file3.tar.gz and videos.tar.bz2 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 folder.
  51
  52 #### Compressing files
  53
  54 ```bash
  55 $ ouch -i file{1..20} -o archive.tar
  56 $ ouch -i Videos/ Movies/ -o media.tar.lzma
  57 $ ouch -i src/ Cargo.toml Cargo.lock -o my_project.tar.gz
  58 ```
  59
  60 ### Error scenarios
  61
  62 #### No clear decompression algorithm
  63
  64 ```bash
  65 $ ouch -i some-file -o some-folder
  66 error: file 'some-file' is not decompressible.
  67 ```
  68
  69 `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.
  70
  71 ```bash
  72 $ ouch -i file other-file -o files.gz
  73 error: cannot compress multiple files directly to Gzip.
  74        Try using an intermediate archival method such as Tar.
  75        Example: filename.tar.gz
  76 ```
  77
  78 Similar errors are shown if the same scenario is applied to `.lz/.lzma` and `.bz/.bz2`.
  79
  80 ## Installation
  81
  82 ### Runtime dependencies
  83
  84 `ouch` depends on a few widespread libraries:
  85 * libbz2
  86 * liblzma
  87
  88 Both should be already installed in any mainstream Linux distribution.
  89
  90 If they're not, then:
  91
  92 * On Debian-based distros
  93
  94 `sudo apt install liblzma-dev libbz2-dev`
  95
  96 * On Arch-based distros
  97
  98 `sudo pacman -S xz bzip2`
  99
 100 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/).
 101
 102 ### Build process
 103
 104 Once the dependency requirements are met:
 105
 106 * Installing from [Crates.io](https://crates.io)
 107
 108 ```bash
 109 cargo install ouch
 110 ```
 111
 112 * Cloning and building
 113
 114 ```bash
 115 git clone https://github.com/vrmiguel/ouch
 116 cargo install --path ouch
 117 # or
 118 cd ouch && cargo run --release
 119 ```
 120
 121 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.
 122
 123 ## Supported operating systems
 124
 125 `ouch` _should_ be cross-platform but is currently only tested (and developed) on Linux, on both x64-64 and ARM.
 126
 127 ## Limitations
 128
 129 `ouch` does encoding and decoding in-memory, so decompressing very large files with `ouch` is not advisable.
 130
 131 ## Contributions
 132
 133 Any contributions and suggestions are welcome!