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 **Note**
  16    * This README represents the new, but not yet implemented, interface that `ouch` will use.
  17    * For current usage instructions, check [the old README](https://github.com/vrmiguel/ouch/blob/0f453e9dfc70066056b9cc40e8032dcc6ee703bc/README.md).
  18
  19 ## Usage
  20
  21 ### Decompressing files
  22
  23 To decompress any number of files, just supply them to `ouch`.
  24
  25 Use the `-o, --output` flag to redirect the output of decompressions to a folder.
  26
  27 ```bash
  28 # Decompress `a.zip`
  29 ouch a.zip
  30
  31 # Decompress multiple files
  32 ouch a.zip b.tar.gz
  33
  34 # Decompress multiple files but inside new_folder
  35 ouch a.zip  b.tar.gz  c.tar.bz2 -o new_folder
  36 ```
  37
  38 ### Compressing files and directories
  39
  40 The `compress` subcommand is able to compress files and folders. The **last** argument will be the **output file**.
  41
  42 The compression format employed will be defined according to the output file's extension.
  43
  44 ```bash
  45 # Compress four files into `archive.zip`
  46 ouch compress a b c d archive.zip
  47
  48 # Compress three files into a `.tar.bz2` archive
  49 ouch compress a.mp4 b.jpg c.png files.tar.bz2
  50
  51 # Compress a folder and a file into `videos.tar.xz`
  52 ouch compress Videos/ funny_meme.mp4 videos.tar.xz
  53 ```
  54
  55 ### Listing the elements of an archive
  56
  57 (TODO -- not implemented at all)
  58
  59 ```
  60 # Shows the files and folders contained in videos.tar.xz
  61 ouch list videos.tar.xz
  62 ```
  63
  64 ## Supported formats
  65
  66
  67 |               | .tar | .zip | .tar.\*¹ | .zip.\*² | .bz, .bz2 | .gz | .xz, .lz, .lzma | .7z |
  68 |:-------------:|:----:|:----:|:--------:|:--------:|:---------:| --- |:---------------:| --- |
  69 | Decompression |  ✓   |  ✓   |    ✓     |    ✓     |     ✓     | ✓   |        ✓        | ✗   |
  70 |  Compression  |  ✓   |  ✓   |    ✓     |    ✓     |     ✓     | ✓   |        ✓        | ✗   |
  71
  72 ```
  73 Note: .tar.*¹: .tar.gz, .tar.bz, .tar.bz2, .tar.xz, .tar.lz, .tar.lzma, .tar.zip
  74       .zip.*²: .zip.gz, .zip.bz, .zip.bz2, .zip.xz, .zip.lz, .zip.lzma, .zip.zip
  75 ```
  76
  77
  78 ## Installation
  79
  80 ### Getting a pre-compiled binary
  81
  82 ```bash
  83 curl -s https://raw.githubusercontent.com/vrmiguel/ouch/master/install.sh | bash
  84 ```
  85
  86 ### Building
  87
  88 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/).
  89
  90 Once [Cargo](https://doc.rust-lang.org/cargo/) is installed, run:
  91
  92 ```bash
  93 cargo install ouch
  94 # or
  95 git clone https://github.com/vrmiguel/ouch
  96 cargo install --path ouch
  97 # or
  98 git clone https://github.com/vrmiguel/ouch
  99 cd ouch && cargo run --release
 100 ```
 101
 102 ## Supported operating systems
 103
 104 `ouch` runs on Linux, macOS and Windows 10. Binaries are available on our [Releases](https://github.com/vrmiguel/ouch/releases) page.
 105 Binaries are also available at the end of each (successful) [GitHub Actions](https://github.com/vrmiguel/ouch/actions) run.
 106
 107 **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.
 108
 109
 110 ## Limitations
 111
 112 `ouch` does encoding and decoding in-memory, so decompressing very large files with it is not advisable.