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