Skip to content

arcuru/cmprss

Repository files navigation

cmprss

build crates.io coverage license

Mirrored on GitHub and Codeberg. GitHub is the official repo, but use either repo to contribute. Issues can't be synced so there may be some duplicates.

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.

Currently supports:

  • bzip2
  • gzip
  • tar
  • xz

Install

Installation is available through source code and cargo. cargo install cmprss will install the latest version.

For Nix users, the repository contains a flake and an overlay. nix run github:arcuru/cmprss

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

cmprss file.txt file.txt.gz

Compress 2 files into a tar archive

cmprss file1.txt file2.txt archive.tar

Compress stdin with xz

cat file.txt | cmprss file.xz

Extract a tar archive to the current directory

cmprss archive.tar

Extract an xz compressed file

cmprss file.xz file.txt

Extract a gzip compressed file to stdout

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

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:

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

Compress 2 files/directories into a tar archive:

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:

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:

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 that pins versions of all packages used by cmprss. It includes a devShell that can be used with direnv 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 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.