README.md

   1 # Ouch!
   2
   3 <!-- ![ouch_image](https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR5ilNDTFZZ-Vy_ctm2YyAe8Yk0UT7lB2hIhg&usqp=CAU)  -->
   4
   5 `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.
   6
   7 - [Usage](#Usage)
   8     - [Decompressing files](#Decompressing-files)
   9     - [Compressing files/directories](#Compressing-files-and-directories)
  10     - [Listing files](#Listing-the-elements-of-an-archive)
  11 - [Supported Formats](#Supported-formats)
  12 - [Installation](#Installation)
  13 - [Supported operating systems](#Supported-operating-systems)
  14
  15 ## Usage
  16
  17 ### Decompressing files
  18
  19 To decompress any number of files, just supply them to `ouch`.
  20
  21 Use the `-o, --output` flag to redirect the output of decompressions to a folder.
  22
  23 ```bash
  24 # Decompress `a.zip`
  25 ouch a.zip
  26
  27 # Decompress multiple files
  28 ouch a.zip b.tar.gz
  29
  30 # Decompress multiple files but inside new_folder
  31 ouch a.zip  b.tar.gz  c.tar.bz2 -o new_folder
  32 ```
  33
  34 ### Compressing files and directories
  35
  36 The `compress` subcommand is able to compress files and folders. The **last** argument will be the **output file**.
  37
  38 The compression format employed will be defined according to the output file's extension.
  39
  40 ```bash
  41 # Compress four files into `archive.zip`
  42 ouch compress a b c d archive.zip
  43
  44 # Compress three files into a `.tar.bz2` archive
  45 ouch compress a.mp4 b.jpg c.png files.tar.bz2
  46
  47 # Compress a folder and a file into `videos.tar.xz`
  48 ouch compress Videos/ funny_meme.mp4 videos.tar.xz
  49 ```
  50
  51 ### Listing the elements of an archive
  52
  53 (TODO -- not implemented at all)
  54
  55 ```
  56 # Shows the files and folders contained in videos.tar.xz
  57 ouch list videos.tar.xz
  58 ```
  59
  60 ## Supported formats
  61
  62
  63 |               | .tar | .zip | .tar.\*¹ | .zip.\*² | .bz, .bz2 | .gz | .xz, .lz, .lzma | .7z |
  64 |:-------------:|:----:|:----:|:--------:|:--------:|:---------:| --- |:---------------:| --- |
  65 | Decompression |  ✓   |  ✓   |    ✓     |    ✓     |     ✓     | ✓   |        ✓        | ✗   |
  66 |  Compression  |  ✓   |  ✓   |    ✓     |    ✓     |     ✓     | ✓   |        ✓        | ✗   |
  67
  68 ```
  69 Note: .tar.*¹: .tar.gz, .tar.bz, .tar.bz2, .tar.xz, .tar.lz, .tar.lzma, .tar.zip
  70       .zip.*²: .zip.gz, .zip.bz, .zip.bz2, .zip.xz, .zip.lz, .zip.lzma, .zip.zip
  71 ```
  72
  73
  74 ## Installation
  75
  76 ### Getting a pre-compiled binary
  77
  78 ```bash
  79 curl -s https://raw.githubusercontent.com/vrmiguel/ouch/master/install.sh | bash
  80 ```
  81
  82 ### Building
  83
  84 A recent [Rust](rust-lang.org) toolchain is needed to build `ouch`. You can install it following the instructions at [rustup.rs](https://rustup.rs/).
  85
  86 Once [Cargo](https://doc.rust-lang.org/cargo/) is installed, run:
  87
  88 ```bash
  89 cargo install ouch
  90 # or
  91 git clone https://github.com/vrmiguel/ouch
  92 cargo install --path ouch
  93 # or
  94 git clone https://github.com/vrmiguel/ouch
  95 cd ouch && cargo run --release
  96 ```
  97
  98 ## Supported operating systems
  99
 100 `ouch` runs on Linux, macOS and Windows 10. Binaries are available on our [Releases](https://github.com/vrmiguel/ouch/releases) page.
 101 Binaries are also available at the end of each (successful) [GitHub Actions](https://github.com/vrmiguel/ouch/actions) run.
 102
 103 **Note on Windows**: colors are currently messed up on PowerShell but work fine on [ConEmu](https://conemu.github.io/). A feature for disabling colors is planned.
 104
 105
 106 ## Limitations
 107
 108 `ouch` does encoding and decoding in-memory, so decompressing very large files with it is not advisable.