this repo has no description
1# cmprss
2
3[](https://github.com/arcuru/cmprss/actions?query=workflow%3ANix)
4[](https://crates.io/crates/cmprss)
5[](https://codecov.io/gh/arcuru/cmprss)
6
7
8**Mirrored on [GitHub](https://github.com/arcuru/cmprss) and [Codeberg](https://codeberg.org/arcuru/cmprss). GitHub is the official repo, but use either repo to contribute. Issues can't be synced so there may be some duplicates.**
9
10A compression multi-tool for the command line.
11Replace `tar` with something you can remember.
12[Relevant XKCD](https://xkcd.com/1168/).
13
14All compression libraries are statically compiled in, so no runtime dependencies required.
15
16Currently supports:
17
18- brotli
19- bzip2
20- gzip
21- lz4
22- lzma (legacy LZMA1)
23- snappy (framed)
24- tar
25- xz
26- zip
27- zstd
28
29## Install
30
31Installation is available through source code and cargo. `cargo install cmprss` will install the latest version.
32
33For Nix users, the repository contains a flake and an overlay. `nix run github:arcuru/cmprss`
34
35A fully static musl-linked binary is also available for Linux: `nix build github:arcuru/cmprss#cmprss-static`
36
37### Shell Completions
38
39The Nix package installs Bash, Fish, and Zsh completions automatically.
40
41For other installations, add the matching snippet to your shell profile. Supported shells: `bash`, `elvish`, `fish`, `powershell`, `zsh`.
42
43Bash (`~/.bashrc`):
44
45```bash
46source <(cmprss completions bash)
47```
48
49Zsh (`~/.zshrc`):
50
51```bash
52source <(cmprss completions zsh)
53```
54
55Fish (`~/.config/fish/config.fish`):
56
57```fish
58cmprss completions fish | source
59```
60
61## Usage
62
63The primary goal is to infer behavior based on the input, so that you don't need to remember esoteric CLI arguments.
64
65`cmprss` supports being very explicit about the inputs and outputs for scripting, but will also behave intelligently when you leave out info.
66
67All commands read from left to right, input is always either piped from `stdin` or the first filename(s) specified, and output is either `stdout` or the last filename/directory.
68
69The easiest way to understand is to look at some examples
70
71Compress a file with gzip
72
73```bash
74cmprss file.txt file.txt.gz
75```
76
77Compress 2 files into a tar archive
78
79```bash
80cmprss file1.txt file2.txt archive.tar
81```
82
83Compress stdin with xz
84
85```bash
86cat file.txt | cmprss file.xz
87```
88
89Extract a tar archive to the current directory
90
91```bash
92cmprss archive.tar
93```
94
95Extract an xz compressed file
96
97```bash
98cmprss file.xz file.txt
99```
100
101Extract a gzip compressed file to stdout
102
103```bash
104cmprss file.txt.gz > file.txt
105```
106
107### Multi-level Compression
108
109`cmprss` supports multi-level archives like `.tar.gz`, `.tar.xz`, or `.zstd.bz2` directly:
110
111```bash
112# Compress a directory to a tar.gz file
113cmprss directory out.tar.gz
114
115# Extract a tar.xz file to a directory
116cmprss --extract archive.tar.xz output_dir
117
118# Gzip an existing tar archive
119cmprss archive.tar archive.tar.gz
120
121# Extract just the xz layer
122cmprss archive.tar.xz archive.tar
123```
124
125The common compound shortcut extensions also work and behave identically to their long forms:
126
127| Shortcut | Equivalent to |
128| -------------- | ------------- |
129| `.tgz` | `.tar.gz` |
130| `.tbz`/`.tbz2` | `.tar.bz2` |
131| `.txz` | `.tar.xz` |
132| `.tzst` | `.tar.zst` |
133
134You can also pass a compound format as the leading argument (like the `tar` subcommand) to make it explicit, without writing out a target filename:
135
136```bash
137# Compress a directory to directory.tar.gz
138cmprss tar.gz directory
139
140# Same, using the shortcut form
141cmprss tgz directory out.tgz
142```
143
144Pipes can still be used if preferred:
145
146```bash
147cmprss tar dir | cmprss gz | cmprss gz -e | cmprss tar -e
148```
149
150### Examples of Explicit Behavior
151
152All these examples will work with _any_ of the supported compression formats, provided that they support the input/output formats.
153
154If output filenames are left out, `cmprss` will try to infer the filename based on the compression type.
155
156Compress a file/directory to a `tar` archive:
157
158```bash
159cmprss tar filename # outputs to filename.tar
160cmprss tar filename my_preferred_output_name.tar
161```
162
163Compress 2 files/directories into a `tar` archive:
164
165```bash
166cmprss tar dir_1/ dir_2/ combined.tar
167cmprss tar file_1.txt file_2.txt # outputs to file_1.txt.tar
168```
169
170Extract a `tar` archive:
171
172```bash
173cmprss tar --extract archive.tar # extracts to the current directory
174cmprss tar -e archive.tar custom_output_directory
175```
176
177`cmprss` will detect if `stdin` or `stdout` is a pipe, and use those for I/O where it makes sense.
178
179Create and extract a `tar.gz` archive with pipes:
180
181```bash
182cmprss tar directory | cmprss gzip > directory.tar.gz
183cmprss gzip --extract directory.tar.gz | cmprss tar -e new_directory
184
185# Or a full roundtrip in one line
186cmprss tar directory_1/ directory_2/ | cmprss gzip | cmprss gzip -e | cmprss tar -e new_directory
187```
188
189## Contributing
190
191### Development Environment
192
193The primary supported developer environment is defined in the `flake.nix` file.
194This is a [Nix Flake](https://nixos.wiki/wiki/Flakes) that pins versions of all packages used by `cmprss`.
195It includes a `devShell` that can be used with [direnv](https://direnv.net/) to use the tools each time you enter the directory.
196
197That being said, `cmprss` is a very standard Rust application and should work with recent Rust toolchains.
198
199The CI runs on both a stable Rust toolchain and the pinned Nix versions to verify correctness of both.
200
201If you run into any issues developing with either the Nix environment or a stable Rust environment, please open a Github issue with the details.
202
203### Conventional Commits
204
205Commits should conform to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
206
207A script to help create conforming commits is provided in `bin/commit.sh`, or via `task commit`.
208
209### Test Coverage
210
211PRs that improve the test coverage are encouraged.
212
213Test coverage can be measured using `cargo llvm-cov report` and `cargo tarpaulin`.