cmprss 0.1.0

cmprss - a compression multi-tool for the CLI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

# cmprss

**Status: Alpha.**
CLI is relatively stable but likely contains bugs, and there may be future breaking changes.

A compression multi-tool for the CLI.
Replace `tar` with something you can remember.
[Relevant XKCD](https://xkcd.com/1168/).

Currently supports:

- gzip
- tar
- xz

## Usage

The primary goal of the CLI is to make it easy and consistent to work with any compression format.
All of the examples will work with _any_ of the supported compression formats.
Though some formats will fail in certain scenarios as not all compression formats support all types of input/output.
For example `tar` is unable to support compressing from `stdin` and extracting to `stdout`, because it expects to operate on files.

All 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.

If output filenames are left out, `cmprss` will try to infer the filename based on the compression type.

### Examples

Compress a file/directory to a `tar` archive:

```bash
cmprss tar filename # outputs to filename.tar
cmprss tar filename my_preferred_output_name.tar
```

Compress 2 files/directories into a `tar` archive:

```bash
cmprss tar dir_1/ dir_2/ combined.tar
cmprss tar file_1.txt file_2.txt # outputs to file_1.txt.tar
```

Extract a `tar` archive:

```bash
cmprss tar --extract archive.tar # extracts to the current directory
cmprss tar -e archive.tar custom_output_directory
```

`cmprss` will detect if `stdin` or `stdout` is a pipe, and use those for I/O where it makes sense.

Create and extract a `tar.gz` archive with pipes:

```bash
cmprss tar directory | cmprss gzip > directory.tar.gz
cmprss gzip --extract directory.tar.gz | cmprss tar -e new_directory

# Or a full roundtrip in one line
cmprss tar directory_1/ directory_2/ | cmprss gzip | cmprss gzip -e | cmprss tar -e new_directory
```

## Contributing

### Development Environment

The primary supported developer environment is defined in the `flake.nix` file.
This is a [Nix Flake](https://nixos.wiki/wiki/Flakes) that pins versions of all packages used by `cmprss`.
It includes a `devShell` that can be used with [direnv](https://direnv.net/) to use the tools each time you enter the directory.

That being said, `cmprss` is a very standard Rust application and should work with recent Rust toolchains.

The CI runs on both a stable Rust toolchain and the pinned Nix versions to verify correctness of both.

If you run into any issues developing with either the Nix environment or a stable Rust environment, please open a Github issue with the details.

### Conventional Commits

Commits should conform to the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard.

### Test Coverage

PRs that improve the test coverage are encouraged.

Test coverage can be measured using `cargo llvm-cov report` and `cargo tarpaulin`.

### @arcuru

I am the only developer on this right now, and I usually develop by committing directly to the `main` branch.
For larger features I _may_ go through a PR to run CI and to have some more easily discoverable documentation of a specific feature.

I will stop committing directly to `main` as soon as someone else submits a non-trivial PR and then submits a request to remove this section of the README.