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## Usage
38
39The primary goal is to infer behavior based on the input, so that you don't need to remember esoteric CLI arguments.
40
41`cmprss` supports being very explicit about the inputs and outputs for scripting, but will also behave intelligently when you leave out info.
42
43All 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.
44
45The easiest way to understand is to look at some examples
46
47Compress a file with gzip
48
49```bash
50cmprss file.txt file.txt.gz
51```
52
53Compress 2 files into a tar archive
54
55```bash
56cmprss file1.txt file2.txt archive.tar
57```
58
59Compress stdin with xz
60
61```bash
62cat file.txt | cmprss file.xz
63```
64
65Extract a tar archive to the current directory
66
67```bash
68cmprss archive.tar
69```
70
71Extract an xz compressed file
72
73```bash
74cmprss file.xz file.txt
75```
76
77Extract a gzip compressed file to stdout
78
79```bash
80cmprss file.txt.gz > file.txt
81```
82
83### Multi-level Compression
84
85`cmprss` supports multi-level archives like `.tar.gz`, `.tar.xz`, or `.zstd.bz2` directly:
86
87```bash
88# Compress a directory to a tar.gz file
89cmprss directory out.tar.gz
90
91# Extract a tar.xz file to a directory
92cmprss --extract archive.tar.xz output_dir
93
94# Gzip an existing tar archive
95cmprss archive.tar archive.tar.gz
96
97# Extract just the xz layer
98cmprss archive.tar.xz archive.tar
99```
100
101The common compound shortcut extensions also work and behave identically to their long forms:
102
103| Shortcut | Equivalent to |
104| -------------- | ------------- |
105| `.tgz` | `.tar.gz` |
106| `.tbz`/`.tbz2` | `.tar.bz2` |
107| `.txz` | `.tar.xz` |
108| `.tzst` | `.tar.zst` |
109
110Pipes can still be used if preferred:
111
112```bash
113cmprss tar dir | cmprss gz | cmprss gz -e | cmprss tar -e
114```
115
116### Examples of Explicit Behavior
117
118All these examples will work with _any_ of the supported compression formats, provided that they support the input/output formats.
119
120If output filenames are left out, `cmprss` will try to infer the filename based on the compression type.
121
122Compress a file/directory to a `tar` archive:
123
124```bash
125cmprss tar filename # outputs to filename.tar
126cmprss tar filename my_preferred_output_name.tar
127```
128
129Compress 2 files/directories into a `tar` archive:
130
131```bash
132cmprss tar dir_1/ dir_2/ combined.tar
133cmprss tar file_1.txt file_2.txt # outputs to file_1.txt.tar
134```
135
136Extract a `tar` archive:
137
138```bash
139cmprss tar --extract archive.tar # extracts to the current directory
140cmprss tar -e archive.tar custom_output_directory
141```
142
143`cmprss` will detect if `stdin` or `stdout` is a pipe, and use those for I/O where it makes sense.
144
145Create and extract a `tar.gz` archive with pipes:
146
147```bash
148cmprss tar directory | cmprss gzip > directory.tar.gz
149cmprss gzip --extract directory.tar.gz | cmprss tar -e new_directory
150
151# Or a full roundtrip in one line
152cmprss tar directory_1/ directory_2/ | cmprss gzip | cmprss gzip -e | cmprss tar -e new_directory
153```
154
155## Contributing
156
157### Development Environment
158
159The primary supported developer environment is defined in the `flake.nix` file.
160This is a [Nix Flake](https://nixos.wiki/wiki/Flakes) that pins versions of all packages used by `cmprss`.
161It includes a `devShell` that can be used with [direnv](https://direnv.net/) to use the tools each time you enter the directory.
162
163That being said, `cmprss` is a very standard Rust application and should work with recent Rust toolchains.
164
165The CI runs on both a stable Rust toolchain and the pinned Nix versions to verify correctness of both.
166
167If you run into any issues developing with either the Nix environment or a stable Rust environment, please open a Github issue with the details.
168
169### Conventional Commits
170
171Commits should conform to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.
172
173A script to help create conforming commits is provided in `bin/commit.sh`, or via `task commit`.
174
175### Test Coverage
176
177PRs that improve the test coverage are encouraged.
178
179Test coverage can be measured using `cargo llvm-cov report` and `cargo tarpaulin`.