Space

A fast disk space analyzer and cleaner powered by Rust! :vulcan_salute:

Description

space is a Command Line Interface (CLI) utility that can be used to visualize and manage disk space.

CLI

Two operating modes are supported:

:one: Text User Interface (TUI)

• Analyzes and displays the apparent size of files in one or more directory trees.
• Enables visual exploration of disk space usage.
• Files or directories may be deleted to free up disk space.
• All files are included and may be visually filtered based on relative size and/or a regex matching the full file path.
• This is the default mode.

:two: Non-interactive, read-only output to the terminal

• Outputs one or more directory trees to the terminal and then exits.
• Relative size filtering may be specified via command line parameters. The default is >= 1%. Use space --help to see options.
• This mode is used when the --non-interactive argument is specified.

:information_source: The apparent size of a file is the size of the file content, which is typically less than the actual space allocated as blocks on the disk. The larger the file, the less significant the difference.

Limitations

• Hard links are considered real files and their sizes will be included.
• Symbolic links are listed but not followed.

Installing the CLI

Homebrew (Linux and MacOS)

brew install emilevr/space/space

In future, space may be upgraded via:

brew upgrade emilevr/space/space

Scoop (Windows)

space is available in the extras bucket.

:one: Add the bucket via the following command, if you haven't done so already:

scoop bucket add extras

:two: Install:

scoop install space

:three: In future, upgrade:

scoop update space

Alternatively, use the following command to install space via the Scoop manifest published by this repo:

scoop install https://emilevr.github.io/space/scoop/space.json

Bash

bash -c "$(curl -fsSL https://raw.githubusercontent.com/emilevr/space/main/install/install.sh)"

PowerShell

If you have PowerShell installed on either Windows, Linux or MacOS, you can run the following in a PowerShell terminal to install (or reinstall) the latest version of space:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # Optional if your current execution policy already allows local scripts
Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/emilevr/space/main/install/install.ps1 | Invoke-Expression

Direct Download

Download and extract the relevant file for your platform and operating system from the list of assets included in the latest release

Notes

Yet another disk space usage utility?

You may have noticed that there are a fair number of disk space usage utilities out there, written in many languages. So why make another one? Well, this kind of project is a great way to learn a new language and a bunch of related stuff, like building and distributing applications for many platforms. It's also fun to write, with some challenges around performance that provide an opportunity to give Rust's "Fearless Concurrency" a spin. The implementation is straight forward and hasn't been optimized much, yet it performs pretty well.

Getting started with this repo

This repository contains:

• A CLI utility.
• A Rust library that can be used to analyze disk space. The library is not published to crates.io, but may be at some point in the future.
• A CLI build tool that takes care of versioning, code coverage and benchmarks.

Prerequisites

• The Rust toolchain must be installed. See rust-toolchain.toml for the currently supported version.
• Visual Studio Code is the recommended IDE. The recommended extensions are listed in the .vscode/extensions.json file and Visual Studio Code should prompt for their installation automatically.

Enabling Git hooks (once off)

After the initial checkout please run the post-checkout hook manually via:

git config core.hooksPath ./.git-hooks
# On MacOS / Linux, make the hook scripts executable. On Windows, comment out the line below:
chmod +x .git-hooks/*
git hook run post-checkout

This will setup the hooks directory, enabling the pre-commit hook to run linting, code coverage and benchmarks.

Building and running the space CLI

To build the library and binaries, simply run cargo build --all-features from the repo root directory. The binaries will be built in the ./target/debug directory. Alternatively use cargo run --bin space to build and run the space CLI.

:information_source: All the commands listed below should also be run from the repo root.

Running Tests

• Run non-interactive tests via cargo test --all-features.
• Run all tests, including interactive. ones via cargo test --all-features -- --include-ignored. Note:this requires a large/maximized terminal window.

Running code format and lint tests

• Run cargo fmt -- --check to check code formatting.
• Clippy comes to the rescue for linting, via cargo clippy.

Debugging

• Debugging profiles for Visual Studio Code have been created in the .vscode directory.
• Tests can be easily run or debugged by using the Run Test or Debug links above each test in the IDE:

Code Coverage

This repo contains a simple Rust build project that takes care of versioning, running code coverage and benchmark tasks.

In order for code coverage to be generated, ensure you have installed llvm-tools via rustup component add llvm-tools.

To generate a code coverage report, run cargo install --path ./buildit && buildit coverage --include-ignored.

Benchmarks

To run a benchmark test, use cargo buildit benchmark.

:information_source: The plan is to make this a comparative benchmark that runs as part of each PR merge build, with the results automatically published to the README.

Contributing

Please read CONTRIBUTING.md for details on the code of conduct and how to submit pull requests.

Versioning

SemVer is used for versioning. For the versions available, see the tags on this repository.

Authors

• Emile van Reenen - initial work - emilevr

Also see the list of contributors to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

• Thanks to all the Rust library contributors out there, especially for those libs used by this project. Keep up the great work! See the relevant Cargo.toml file dependencies.
• Thanks to the many disk space usage tool authors out there, written in Rust and other languages. Challenge accepted! :relaxed: The future benchmark section will acknowledge a few of these.
• Thanks to PurpleBooth for some great repo templates.