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