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
177Append new entries to an existing `tar` or `zip` archive:
178
179```bash
180cmprss tar --append new_file.txt archive.tar
181cmprss zip -a new_file.txt extra_dir/ archive.zip
182```
183
184`--append` only works for container formats that can grow in place. Stream codecs (gzip, xz, …) and compound pipelines like `tar.gz` have no way to append without rewriting the whole archive, so they error instead of silently doing the wrong thing.
185
186`cmprss` will detect if `stdin` or `stdout` is a pipe, and use those for I/O where it makes sense.
187
188Create and extract a `tar.gz` archive with pipes:
189
190```bash
191cmprss tar directory | cmprss gzip > directory.tar.gz
192cmprss gzip --extract directory.tar.gz | cmprss tar -e new_directory
193
194# Or a full roundtrip in one line
195cmprss tar directory_1/ directory_2/ | cmprss gzip | cmprss gzip -e | cmprss tar -e new_directory
196```
197
198## Contributing
199
200### Development Environment
201
202The primary supported developer environment is defined in the `flake.nix` file.
203This is a [Nix Flake](https://nixos.wiki/wiki/Flakes) that pins versions of all packages used by `cmprss`.
204It includes a `devShell` that can be used with [direnv](https://direnv.net/) to use the tools each time you enter the directory.
205
206That being said, `cmprss` is a very standard Rust application and should work with recent Rust toolchains.
207
208The CI runs on both a stable Rust toolchain and the pinned Nix versions to verify correctness of both.
209
210If you run into any issues developing with either the Nix environment or a stable Rust environment, please open a Github issue with the details.
211
212### Conventional Commits
213
214Commits should conform to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
215
216A script to help create conforming commits is provided in `bin/commit.sh`, or via `task commit`.
217
218### Test Coverage
219
220PRs that improve the test coverage are encouraged.
221
222Test coverage can be measured using `cargo llvm-cov report` and `cargo tarpaulin`.