an efficient binary archive format
1# bindle-file
2
3[bindle](https://en.wikipedia.org/wiki/Bindle) is a fast/efficient, binary archive format.
4
5The 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.
6
7## Installation
8
9The CLI can be installed by running:
10
11```sh
12cargo install bindle-file
13```
14
15## Rust
16
17```rust
18use bindle_file::{Bindle, Compress};
19
20// Create or open an archive
21let mut archive = Bindle::open("data.bndl")?;
22
23// Add files
24archive.add("config.json", data, Compress::None)?;
25archive.save()?;
26
27// Read files
28let data = archive.read("config.json").unwrap();
29
30// Update by shadowing (old data remains until vacuum)
31archive.add("config.json", new_data, Compress::None)?;
32archive.save()?;
33
34// Reclaim space from shadowed entries
35archive.vacuum()?;
36```
37
38## C
39
40```c
41#include "bindle.h"
42
43Bindle* bindle = bindle_open("data.bndl");
44bindle_add(bindle, "file.txt", data, len, BindleCompressNone);
45bindle_save(bindle);
46
47size_t len = bindle_entry_size(bindle, "file.txt");
48uint8_t *data = malloc(len);
49assert(bindle_read(bindle, "file.txt", data) == len);
50// Or for uncompressed entries, read directly without decompression
51uint8_t* raw = bindle_read_uncompressed_direct(bindle, "file.txt", &size);
52
53free(data);
54bindle_close(bindle);
55```
56
57Run:
58
59```sh
60make build
61```
62
63To build `libbindle` and copy in to the root of repository
64
65## CLI
66
67The `bindle` command provides basic operations:
68
69```bash
70bindle add archive.bndl file.txt
71bindle read archive.bndl file.txt
72bindle pack archive.bndl /some/dir
73bindle unpack archive.bndl /unpack/to/dir
74bindle list archive.bndl
75bindle vacuum archive.bndl
76```
77
78## Format
79
80See [SPEC.md](SPEC.md) for the binary format specification.