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
134Pipes can still be used if preferred:
135
136```bash
137cmprss tar dir | cmprss gz | cmprss gz -e | cmprss tar -e
138```
139
140### Examples of Explicit Behavior
141
142All these examples will work with _any_ of the supported compression formats, provided that they support the input/output formats.
143
144If output filenames are left out, `cmprss` will try to infer the filename based on the compression type.
145
146Compress a file/directory to a `tar` archive:
147
148```bash
149cmprss tar filename # outputs to filename.tar
150cmprss tar filename my_preferred_output_name.tar
151```
152
153Compress 2 files/directories into a `tar` archive:
154
155```bash
156cmprss tar dir_1/ dir_2/ combined.tar
157cmprss tar file_1.txt file_2.txt # outputs to file_1.txt.tar
158```
159
160Extract a `tar` archive:
161
162```bash
163cmprss tar --extract archive.tar # extracts to the current directory
164cmprss tar -e archive.tar custom_output_directory
165```
166
167`cmprss` will detect if `stdin` or `stdout` is a pipe, and use those for I/O where it makes sense.
168
169Create and extract a `tar.gz` archive with pipes:
170
171```bash
172cmprss tar directory | cmprss gzip > directory.tar.gz
173cmprss gzip --extract directory.tar.gz | cmprss tar -e new_directory
174
175# Or a full roundtrip in one line
176cmprss tar directory_1/ directory_2/ | cmprss gzip | cmprss gzip -e | cmprss tar -e new_directory
177```
178
179## Contributing
180
181### Development Environment
182
183The primary supported developer environment is defined in the `flake.nix` file.
184This is a [Nix Flake](https://nixos.wiki/wiki/Flakes) that pins versions of all packages used by `cmprss`.
185It includes a `devShell` that can be used with [direnv](https://direnv.net/) to use the tools each time you enter the directory.
186
187That being said, `cmprss` is a very standard Rust application and should work with recent Rust toolchains.
188
189The CI runs on both a stable Rust toolchain and the pinned Nix versions to verify correctness of both.
190
191If you run into any issues developing with either the Nix environment or a stable Rust environment, please open a Github issue with the details.
192
193### Conventional Commits
194
195Commits should conform to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
196
197A script to help create conforming commits is provided in `bin/commit.sh`, or via `task commit`.
198
199### Test Coverage
200
201PRs that improve the test coverage are encouraged.
202
203Test coverage can be measured using `cargo llvm-cov report` and `cargo tarpaulin`.