# bfree

Memory stats for humans.

`bfree` is a lightweight Rust CLI that provides a clearer, human-oriented view of Linux memory and swap usage.

It keeps the speed and simplicity of `free` while improving readability and presenting practical memory semantics by default.

## Features

- Human-readable sizes and percentages
- Multiple output modes: `compact` (default), `extended`, and `visual`
- Structured output: `--json` and `--yaml` (compact by default, extended with `--extended`)
- Linux-only, using `/proc/meminfo`
- Small dependency surface and fast startup

## Installation

### Cargo

`bfree` is published on crates.io:

- https://crates.io/crates/bfree

```bash
cargo install bfree
```

### From source

```bash
git clone https://github.com/glexposito/bfree
cd bfree
cargo build --release
./target/release/bfree
```

### Arch Linux (AUR)

Release publishing to AUR is automated by the project release workflow.

Package page: https://aur.archlinux.org/packages/bfree

```bash
yay -S bfree
```

## Usage

```bash
bfree --help
```

## Output Semantics

`bfree` currently uses the following memory model:

- `used = MemTotal - MemAvailable`
- `avail = MemAvailable`
- `cache = Cached + SReclaimable - Shmem` (effective reclaimable cache)

Mode notes:

- `compact` (default) shows `used / total` and percentage for memory and swap.
- `--extended` and `--visual` also show `cache` and `avail`.
- `--json` and `--yaml` export machine-friendly structures for compact/extended modes.

## Project Status

Implemented:

- Linux `/proc/meminfo` parser with typed error handling
- Compact, extended, and visual renderers
- Unit tests for memory math and render behavior
- CI for pushes and pull requests
- Release automation for GitHub releases and AUR updates

Planned:

- Fedora COPR packaging and publish pipeline
- Container/cgroup-aware mode
- PSI (Pressure Stall Information) support

## Development

```bash
cargo run --
```

```bash
cargo test --all-targets --all-features
```

## Contributing

Issues and pull requests are welcome.

## License

MIT License. See [LICENSE](LICENSE).