d39804a5a6ba208159356b6ecd8308b559c588d0

Message

docs(universalarchive): expand documentation (#13136)

Diff

This diff is truncated to protect this page.

  1diff --git a/plugins/universalarchive/README.md b/plugins/universalarchive/README.md
  2index 93a1bd9fc47ddc975d638b55b061cc6d8f1e2646..bcd33cea0440926aa76ceac991d297f161e11b28 100644
  3--- a/plugins/universalarchive/README.md
  4+++ b/plugins/universalarchive/README.md
  5@@ -1,46 +1,76 @@
  6 # universalarchive plugin
  7 
  8-Lets you compress files by a command `ua <format> <files>`, supporting various
  9-compression formats (e.g. 7z, tar.gz, lzma, ...).
 10+The `universalarchive` plugin provides a convenient command-line interface for archiving files and directories using a wide variety of compression formats - without having to remember the exact syntax for each tool.
 11 
 12-To enable it, add `universalarchive` to the plugins array in your zshrc file:
 13+To enable it, add `universalarchive` to the plugins array in your `.zshrc` file:
 14 
 15 ```zsh
 16 plugins=(... universalarchive)
 17 ```
 18 
 19+## Features
 20+ - Compress files and directories using a simple, unified command: ua <format> <files>
 21+ - Automatically detects file/directory names to generate appropriate output names
 22+ - Supports fallback naming if an output file already exists
 23+ - Works with many common and advanced compression formats
 24+ - Designed for simplicity and quick use in the terminal
 25+
 26 ## Usage
 27 
 28-Run `ua <format> <files>` to compress `<files>` into an archive file using `<format>`.
 29-For example:
 30+Basic command format:
 31+```sh
 32+ua <format> <files...>
 33+```
 34+- `<format>`: the archive format to use (e.g., `zip`, `tar.gz`, `xz`, `7z`, etc.)
 35+- `<files...>`: one or more files or directories to compress
 36+
 37+## Examples:
 38+
 39+Compresses `notes.txt` and `images` into `notes.zip`
 40+```sh
 41+ua zip notes.txt images/
 42+```
 43+
 44+Creates `myproject.tar.gz`
 45+```sh
 46+ua tar.gz myproject/
 47+```
 48 
 49+Compresses all .log files into `current_folder.xz`
 50 ```sh
 51-ua xz *.html
 52+ua xz *.log
 53 ```
 54 
 55-this command will compress all `.html` files in directory `folder` into `folder.xz`.
 56-
 57-This plugin saves you from having to remember which command line arguments compress a file.
 58-
 59-## Supported compression formats
 60-
 61-| Extension        | Description                    |
 62-|:-----------------|:-------------------------------|
 63-| `7z`             | 7zip file                      |
 64-| `bz2`            | Bzip2 file                     |
 65-| `gz`             | Gzip file                      |
 66-| `lzma`           | LZMA archive                   |
 67-| `lzo`            | LZO archive                    |
 68-| `rar`            | WinRAR archive                 |
 69-| `tar`            | Tarball                        |
 70-| `tbz`/`tar.bz2`  | Tarball with bzip2 compression |
 71-| `tgz`/`tar.gz`   | Tarball with gzip compression  |
 72-| `tlz`/`tar.lzma` | Tarball with lzma compression  |
 73-| `txz`/`tar.xz`   | Tarball with lzma2 compression |
 74-| `tZ`/`tar.Z`     | Tarball with LZW compression   |
 75-| `xz`             | LZMA2 archive                  |
 76-| `Z`              | Z archive (LZW)                |
 77-| `zip`            | Zip archive                    |
 78-| `zst`            | Zstd archive                   |
 79-
 80-See [list of archive formats](https://en.wikipedia.org/wiki/List_of_archive_formats) for more information regarding the archive formats.
 81+The plugin will generate a default archive filename based on the input:
 82+ - For a file, the output is derived from the file name without its extension.
 83+ - For a directory, it uses the directory name.
 84+ - For multiple files, it uses the name of the common parent directory.
 85+
 86+ If the output file already exists, a unique filename is generated using `mktemp`.
 87+
 88+## Supported Archive Formats
 89+
 90+| Format           | Description                    | Tool Used        |
 91+|:-----------------|:-------------------------------|:-----------------|
 92+| `7z`             | 7zip archive                   | `7z`             |
 93+| `bz2`            | Bzip2-compressed file          | `bzip2`          |
 94+| `gz`             | Gzip-compressed file           | `gzip`           |
 95+| `lzma`           | LZMA-compressed file           | `lzma`           |
 96+| `lzo`            | LZO-compressed file            | `lzop`           |
 97+| `rar`            | WinRAR archive                 | `rar`            |
 98+| `tar`            | Uncompressed tarball           | `tar`            |
 99+| `tbz`,`tar.bz2`  | Tarball compressed with Bzip2  | `tar + bzip2`    |
100+| `tgz`,`tar.gz`   | Tarball compressed with Gzip   | `tar + gzip`     |
101+| `tlz`,`tar.lzma` | Tarball compressed with LZMA   | `tar + lzma`     |
102+| `txz`,`tar.xz`   | Tarball compressed with LZMA2  | `tar + xz`       |
103+| `tZ`,`tar.Z`     | Tarball compressed with LZW    | `tar + compress` |
104+| `xz`             | XZ-compressed file             | `xz`             |