# bindle-file

[bindle](https://en.wikipedia.org/wiki/Bindle) is a fast/efficient, binary archive format.

The format uses memory-mapped I/O for fast reads, optional zstd compression, and supports append-only writes with shadowing for updates. Files can be added incrementally without rewriting the entire archive.

## Installation

The CLI can be installed by running:

```sh
cargo install bindle-file
```

## Rust

```rust
use bindle_file::{Bindle, Compress};

// Create or open an archive
let mut archive = Bindle::open("data.bndl")?;

// Add files
archive.add("config.json", data, Compress::None)?;
archive.save()?;

// Read files
let data = archive.read("config.json").unwrap();

// Update by shadowing (old data remains until vacuum)
archive.add("config.json", new_data, Compress::None)?;
archive.save()?;

// Reclaim space from shadowed entries
archive.vacuum()?;
```

## C

```c
#include "bindle.h"

Bindle* bindle = bindle_open("data.bndl");
bindle_add(bindle, "file.txt", data, len, BindleCompressNone);
bindle_save(bindle);

size_t len = bindle_entry_size(bindle, "file.txt");
uint8_t *data = malloc(len);
assert(bindle_read(bindle, "file.txt", data) == len);
// Or for uncompressed entries, read directly without decompression
uint8_t* raw = bindle_read_uncompressed_direct(bindle, "file.txt", &size);

free(data);
bindle_close(bindle);
```

Run:

```sh
make build
```

To build `libbindle` and copy in to the root of repository

## CLI

The `bindle` command provides basic operations:

```bash
bindle add archive.bndl file.txt
bindle read archive.bndl file.txt
bindle pack archive.bndl /some/dir
bindle unpack archive.bndl /unpack/to/dir
bindle list archive.bndl
bindle vacuum archive.bndl
```

## Format

See [SPEC.md](SPEC.md) for the binary format specification.