Skip to content

Commit aeb013c

Browse files
artobartob
committed
Improve the CLI's user experience.
1 parent 4efe55b commit aeb013c

16 files changed

Lines changed: 515 additions & 94 deletions

‎.config/readmer/README.md.liquid‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,7 @@ bundle add bitcache
110110
{% render 'data/readmer/bitcache.sh-session' %}
111111

112112
- [`bitcache clear`](#bitcache-clear) - Remove all blobs from the repository
113+
- [`bitcache compact`](#bitcache-compact) - Compact the repository's physical storage
113114
- [`bitcache export`](#bitcache-export) - Export all blobs in the repository into a tarball
114115
- [`bitcache get`](#bitcache-get) - Fetch blob(s) from the repository, writing their contents to stdout
115116
- [`bitcache has`](#bitcache-has) - Check whether the repository contains blob(s) with the given ID(s)
@@ -126,6 +127,10 @@ bundle add bitcache
126127

127128
{% render 'data/readmer/bitcache-clear.sh-session' %}
128129

130+
#### `bitcache compact`
131+
132+
{% render 'data/readmer/bitcache-compact.sh-session' %}
133+
129134
#### `bitcache export`
130135

131136
{% render 'data/readmer/bitcache-export.sh-session' %}
@@ -170,6 +175,8 @@ bundle add bitcache
170175

171176
{% render 'data/readmer/bitcache-sync.sh-session' %}
172177

178+
### Configuration File
179+
173180
### Storage Adapters
174181

175182
{% render 'data/adapters.psv' %}

‎README.md‎

Lines changed: 126 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -125,23 +125,26 @@ Bitcache is a distributed content-addressable storage (CAS) system.
125125
Usage: bitcache [OPTIONS] [COMMAND]
126126

127127
General commands:
128-
id Compute the BLAKE3 hash of the given file(s)
129-
help Print this message or the help of the given subcommand(s)
128+
id Compute the BLAKE3 hash of the given file(s), or of stdin
129+
help Print this message or the help of the given subcommand(s)
130130

131131
Current repository commands (`$BITCACHE_URL`, default `./.bitcache/`):
132-
init Initialize a new repository in `./.bitcache/`
133-
list List the IDs of the blobs in the repository, in ascending order
134-
has Check whether the repository contains blob(s) with the given ID(s)
135-
get Fetch blob(s) from the repository, writing their contents to stdout
136-
put Store the given file(s) into the repository as blob(s)
137-
rm Remove blob(s) with the given ID(s) from the repository
138-
clear Remove all blobs from the repository
139-
export Export all blobs in the repository into a tarball
132+
init Initialize a new repository in `./.bitcache/`
133+
list List the IDs of the blobs in the repository, in ascending order
134+
has Check whether the repository contains blob(s) with the given ID(s)
135+
get Fetch blob(s) from the repository, writing their contents to stdout
136+
put Store the given file(s) into the repository as blob(s)
137+
rm Remove blob(s) with the given ID(s) from the repository
138+
clear Remove all blobs from the repository
139+
export Export all blobs in the repository into a tarball
140140

141141
Remote repository commands:
142-
push Copy blobs missing from the given remote repositories to them
143-
pull Copy blobs missing from the current repository from the given remotes
144-
sync Synchronize with the given remote repositories, in both directions
142+
push Copy blobs missing from the given remote repositories to them
143+
pull Copy blobs missing from the current repository from the given remotes
144+
sync Synchronize with the given remote repositories, in both directions
145+
146+
Other commands:
147+
compact Compact the repository's physical storage
145148

146149
Options::
147150
--color <COLOR>
@@ -167,6 +170,7 @@ Options::
167170
```
168171

169172
- [`bitcache clear`](#bitcache-clear) - Remove all blobs from the repository
173+
- [`bitcache compact`](#bitcache-compact) - Compact the repository's physical storage
170174
- [`bitcache export`](#bitcache-export) - Export all blobs in the repository into a tarball
171175
- [`bitcache get`](#bitcache-get) - Fetch blob(s) from the repository, writing their contents to stdout
172176
- [`bitcache has`](#bitcache-has) - Check whether the repository contains blob(s) with the given ID(s)
@@ -209,20 +213,66 @@ Options:
209213
Print help (see a summary with '-h')
210214
```
211215

216+
#### `bitcache compact`
217+
218+
```shellsession
219+
$ bitcache compact --help
220+
Compact the repository's physical storage.
221+
222+
Filesystem repositories rewrite stored blobs using the requested compression scheme and clean up orphaned temporary artifacts. Other repository backends may perform no maintenance.
223+
224+
Usage: bitcache compact [OPTIONS]
225+
226+
Options:
227+
--color <COLOR>
228+
Set the color output mode
229+
230+
[default: auto]
231+
[possible values: auto, always, never]
232+
233+
--compress <SCHEME>
234+
The target compression scheme for stored blobs.
235+
236+
One of `none`, `xz`, `xz:fast`, or `xz:best` (`xz` is an alias for `xz:fast`). Defaults to the `compress` directive of the `[bitcache.compact]` config section, or else `xz`.
237+
238+
-d, --debug
239+
Enable debugging output
240+
241+
-v, --verbose...
242+
Enable verbose output (may be repeated for more verbosity)
243+
244+
-h, --help
245+
Print help (see a summary with '-h')
246+
```
247+
212248
#### `bitcache export`
213249

214250
```shellsession
215251
$ bitcache export --help
216-
Export all blobs in the repository into a tarball
252+
Export all blobs in the repository into a tarball.
217253

218-
Usage: bitcache export [OPTIONS] --output <FILE>
254+
Without `--output`, the tar stream is written to stdout, so it can be piped to `xz`, `bzip2`, `gzip`, etc.
255+
256+
Usage: bitcache export [OPTIONS]
219257

220258
Options:
221-
--color <COLOR> Set the color output mode [default: auto] [possible values: auto, always, never]
222-
-o, --output <FILE> The path to the tarball file to create
223-
-d, --debug Enable debugging output
224-
-v, --verbose... Enable verbose output (may be repeated for more verbosity)
225-
-h, --help Print help
259+
--color <COLOR>
260+
Set the color output mode
261+
262+
[default: auto]
263+
[possible values: auto, always, never]
264+
265+
-o, --output <FILE>
266+
The path to the tarball file to create (default: stdout)
267+
268+
-d, --debug
269+
Enable debugging output
270+
271+
-v, --verbose...
272+
Enable verbose output (may be repeated for more verbosity)
273+
274+
-h, --help
275+
Print help (see a summary with '-h')
226276
```
227277

228278
#### `bitcache get`
@@ -231,13 +281,15 @@ Options:
231281
$ bitcache get --help
232282
Fetch blob(s) from the repository, writing their contents to stdout.
233283

284+
IDs may be given as unambiguous hexadecimal prefixes: each prefix resolves to the first matching blob ID in the repository.
285+
234286
Exits with a nonzero status unless all of the given blobs were found in the repository.
235287

236288
Usage: bitcache get [OPTIONS] [IDS]...
237289

238290
Arguments:
239291
[IDS]...
240-
The IDs of the blob(s) to fetch
292+
The IDs (or unambiguous ID prefixes) of the blob(s) to fetch
241293

242294
Options:
243295
--color <COLOR>
@@ -246,9 +298,26 @@ Options:
246298
[default: auto]
247299
[possible values: auto, always, never]
248300

301+
-n, --lines <COUNT>
302+
Print only the first COUNT lines of each blob
303+
249304
-d, --debug
250305
Enable debugging output
251306

307+
-f, --format <FORMAT>
308+
The output format: `raw` (the default) or `base64`
309+
310+
Possible values:
311+
- raw: The blob's raw contents
312+
- base64: ASCII-armored (Base64-encoded) contents, one line per blob
313+
314+
[default: raw]
315+
316+
-o, --output <FILE>
317+
Write the output to this file instead of stdout.
318+
319+
With a single blob, raw output, and no line limit, filesystem repositories reflink uncompressed blobs to the output file on supporting filesystems, avoiding a data copy.
320+
252321
-v, --verbose...
253322
Enable verbose output (may be repeated for more verbosity)
254323

@@ -293,15 +362,15 @@ Options:
293362

294363
```shellsession
295364
$ bitcache id --help
296-
Compute the BLAKE3 hash of the given file(s).
365+
Compute the BLAKE3 hash of the given file(s), or of stdin.
297366

298-
Prints the ID each file would have as a blob, one per line, without accessing or modifying any repository.
367+
Prints the ID each file would have as a blob, one per line, without accessing or modifying any repository. With no files (or with `-`), reads from standard input.
299368

300369
Usage: bitcache id [OPTIONS] [FILES]...
301370

302371
Arguments:
303372
[FILES]...
304-
The paths to the file(s) to hash
373+
The paths to the file(s) to hash (`-` or none for stdin)
305374

306375
Options:
307376
--color <COLOR>
@@ -317,8 +386,6 @@ Options:
317386
- hex: Hexadecimal (aka Base16)
318387
- base58: Base58
319388

320-
[default: hex]
321-
322389
-d, --debug
323390
Enable debugging output
324391

@@ -335,7 +402,8 @@ Options:
335402
$ bitcache init --help
336403
Initialize a new repository in `./.bitcache/`.
337404

338-
Creates an empty repository in the `./.bitcache/` directory of the current working directory; `$BITCACHE_URL` is ignored.
405+
Creates an empty repository in the `./.bitcache/` directory of the current working directory; `$BITCACHE_URL` is ignored. The given options are recorded in the created `.bitcache/config.toml`; an existing
406+
configuration file is never overwritten.
339407

340408
Usage: bitcache init [OPTIONS]
341409

@@ -346,12 +414,30 @@ Options:
346414
[default: auto]
347415
[possible values: auto, always, never]
348416

417+
--hashing <ALGORITHM>
418+
The content-hashing algorithm to use (only `blake3`)
419+
420+
--capacity <COUNT>
421+
A capacity hint for how many blobs will be stored.
422+
423+
A count with an optional `K`, `M`, `B`, or `T` suffix (e.g., `100M` for one hundred million).
424+
349425
-d, --debug
350426
Enable debugging output
351427

428+
--encoding <FORMAT>
429+
The default encoding for displaying blob IDs
430+
431+
Possible values:
432+
- hex: Hexadecimal (aka Base16)
433+
- base58: Base58
434+
352435
-v, --verbose...
353436
Enable verbose output (may be repeated for more verbosity)
354437

438+
--without-git
439+
Skip creating the `.gitattributes` and `.gitignore` files
440+
355441
-h, --help
356442
Print help (see a summary with '-h')
357443
```
@@ -365,7 +451,11 @@ List the IDs of the blobs in the repository, in ascending order.
365451
With `--verbose` (repeatable), appends further tab-separated columns to each line: the blob's byte size, media type, creation timestamp, last-update timestamp, last-access timestamp, and expiration
366452
timestamp.
367453

368-
Usage: bitcache list [OPTIONS]
454+
Usage: bitcache list [OPTIONS] [PREFIX]
455+
456+
Arguments:
457+
[PREFIX]
458+
List only IDs whose hexadecimal encoding begins with this prefix
369459

370460
Options:
371461
--color <COLOR>
@@ -381,17 +471,12 @@ Options:
381471
- hex: Hexadecimal (aka Base16)
382472
- base58: Base58
383473

384-
[default: hex]
474+
-a, --after <ID>
475+
List only IDs ordered strictly after this one
385476

386477
-d, --debug
387478
Enable debugging output
388479

389-
-p, --prefix <PREFIX>
390-
List only IDs whose hexadecimal encoding begins with this prefix
391-
392-
-a, --after <ID>
393-
List only IDs ordered strictly after this one
394-
395480
-n, --limit <COUNT>
396481
List at most this many IDs
397482

@@ -492,7 +577,10 @@ Options:
492577
- hex: Hexadecimal (aka Base16)
493578
- base58: Base58
494579

495-
[default: hex]
580+
--compress <SCHEME>
581+
The compression scheme for physically storing the blob(s).
582+
583+
One of `none`, `xz`, `xz:fast`, or `xz:best` (`xz` is an alias for `xz:fast`). Defaults to the `compress` directive of the `[bitcache.put]` config section, or else `none`.
496584

497585
-d, --debug
498586
Enable debugging output
@@ -576,6 +664,8 @@ Options:
576664
Print help (see a summary with '-h')
577665
```
578666

667+
### Configuration File
668+
579669
### Storage Adapters
580670

581671
| URL Scheme | Adapter Crate | `ls` | `get` | `put` | `rm` | `clear` |

‎data/readmer/bitcache-compact.sh-session‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
$ bitcache compact --help
2+
Compact the repository's physical storage.
3+
4+
Filesystem repositories rewrite stored blobs using the requested compression scheme and clean up orphaned temporary artifacts. Other repository backends may perform no maintenance.
5+
6+
Usage: bitcache compact [OPTIONS]
7+
8+
Options:
9+
--color <COLOR>
10+
Set the color output mode
11+
12+
[default: auto]
13+
[possible values: auto, always, never]
14+
15+
--compress <SCHEME>
16+
The target compression scheme for stored blobs.
17+
18+
One of `none`, `xz`, `xz:fast`, or `xz:best` (`xz` is an alias for `xz:fast`). Defaults to the `compress` directive of the `[bitcache.compact]` config section, or else `xz`.
19+
20+
-d, --debug
21+
Enable debugging output
22+
23+
-v, --verbose...
24+
Enable verbose output (may be repeated for more verbosity)
25+
26+
-h, --help
27+
Print help (see a summary with '-h')

‎data/readmer/bitcache-export.sh-session‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,25 @@
11
$ bitcache export --help
2-
Export all blobs in the repository into a tarball
2+
Export all blobs in the repository into a tarball.
33

4-
Usage: bitcache export [OPTIONS] --output <FILE>
4+
Without `--output`, the tar stream is written to stdout, so it can be piped to `xz`, `bzip2`, `gzip`, etc.
5+
6+
Usage: bitcache export [OPTIONS]
57

68
Options:
7-
--color <COLOR> Set the color output mode [default: auto] [possible values: auto, always, never]
8-
-o, --output <FILE> The path to the tarball file to create
9-
-d, --debug Enable debugging output
10-
-v, --verbose... Enable verbose output (may be repeated for more verbosity)
11-
-h, --help Print help
9+
--color <COLOR>
10+
Set the color output mode
11+
12+
[default: auto]
13+
[possible values: auto, always, never]
14+
15+
-o, --output <FILE>
16+
The path to the tarball file to create (default: stdout)
17+
18+
-d, --debug
19+
Enable debugging output
20+
21+
-v, --verbose...
22+
Enable verbose output (may be repeated for more verbosity)
23+
24+
-h, --help
25+
Print help (see a summary with '-h')

0 commit comments

Comments
 (0)