cmprss 0.2.0

A compression multi-tool for the command line.
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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# cmprss

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

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

Currently supports:

- bzip2
- gzip
- tar
- xz

## Usage

The primary goal is to infer behavior based on the input, so that you don't need to remember esoteric CLI arguments.

`cmprss` supports being very explicit about the inputs and outputs for scripting, but will also behave intelligently when you leave out info.

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.

The easiest way to understand is to look at some examples

Compress a file with gzip

```bash
cmprss file.txt file.txt.gz
```

Compress 2 files into a tar archive

```bash
cmprss file1.txt file2.txt archive.tar
```

Compress stdin with xz

```bash
cat file.txt | cmprss file.xz
```

Extract a tar archive to the current directory

```bash
cmprss archive.tar
```

Extract an xz compressed file

```bash
cmprss file.xz file.txt
```

Extract a gzip compressed file to stdout

```bash
cmprss file.txt.gz > file.txt
```

`cmprss` doesn't yet support multiple levels of archiving, like `.tar.gz`, but they are easy to work with using pipes

```bash
cmprss tar uncompressed_dir | cmprss gz > out.tar.gz
cmprss gzip --extract out.tar.gz | cmprss tar -e output_dir

# Or a full roundtrip in one line
cmprss tar dir | cmprss gz | cmprss gz -e | cmprss tar -e
```

### Examples of Explicit Behavior

All these examples will work with _any_ of the supported compression formats, provided that they support the input/output formats.

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

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.

A script to help create conforming commits is provided in `bin/commit.sh`, or via `task commit`.

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