rocfl

rocfl is a command line utility for working with OCFL repositories. It currently only supports read operations.

Installation

You can either download a pre-built binary from the releases page, or build your own copy locally.

Local Build

1. Install Rust, and make sure cargo is on your PATH
2. Execute: cargo install rocfl
3. Verify the install: rocfl help

Usage

It is intended to be run from within an OCFL repository's storage root. I can be run outside of a storage root by specifying the repository root using the --root option.

Objects are identified by crawling the directories under the storage root. It does not presently map object IDs directly to storage directories.

The following is an overview of the features that rocfl supports. For a detailed description of all of the options available, consult the builtin help by executing rocfl help or rocfl help <COMMAND>.

List

The ls operation can be used to either list all of the objects in a repository or list all of the files in an OCFL object. When listing files, only files in the HEAD object state are returned. Previous versions can be queried with the -v option.

Examples

Listing Objects

The following command lists all of the object IDs in a repository that's rooted in the current working directory:

console rocfl ls

This lists the same objects but with additional details, current version and updated date:

console rocfl ls -l

Adding the -p flag additionally provides the path from the storage root to the object:

console rocfl ls -lp

A subset of objects can be listed by providing a glob pattern to match on:

console rocfl ls -lo foo*

Listing Object Contents

The contents of an object's current state are displayed by invoking ls on a specific object ID:

console rocfl ls foobar

With the -l flag, additional details are displayed. In this case, the version and date indicate when the individual file was last updated:

console rocfl ls -l foobar

The -p flag can also be used here to display the paths to the physical files on disk:

console rocfl ls -p foobar

The contents of previous versions are displayed by using the -v option. The following command displays the files that were in the first version of the object:

console rocfl ls -v1 foobar

An object's contents can be filtered by specifying a glob pattern to match on:

console rocfl ls foobar '*.txt'

The output is sorted by name by default, but can also be sorted version or updated date:

console rocfl ls -lsversion foobar

Log

The log operation displays the version metadata for all versions of an object. It can also be executed on a file within an object, in which case only versions that affected the specified file are displayed.

Examples

Show all of the versions of an object in ascending order:

console rocfl log foobar

Only display the five most recent versions:

console rocfl log -rn5 foobar

Show all of the versions, but formatted so each version is on a single line:

console rocfl log -c foobar

Show all of the versions that affected a specific file:

console rocfl log foobar file1.txt

Show

The show operation displays everything that changed in an object within a specific version. If no version is specified, the most recent changes are shown.

Examples

Show the changes in the most recent version:

console rocfl show foobar

Show the changes in the first version:

console rocfl show foobar v1

Don't show the version metadata; only show the files that changed:

console rocfl show -m foobar

Diff

The diff operation displays the files that changed between two specific versions.

Example

Show the changes between the second and fourth versions:

console rocfl diff v2 v4