rocfl
rocfl
is a command line utility for working with OCFL repositories.
It currently only supports read operations.
rocfl
is able to interact with OCFL repositories located on the local filesystem or in S3. However, the
S3 support is currently very slow. Listing all of the objects in an S3 repository will always be slow, but
performance when interacting with individual objects will improve once it's possible to navigate directly to
an object rather than having to crawl the entire repository looking for it.
Installation
You can either download a pre-built binary from the releases page, or build your own copy locally.
Local Build
- Install Rust, and make sure
cargo
is on yourPATH
- Execute:
cargo install rocfl
- 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:
rocfl ls
This lists the same objects but with additional details, current version and updated date:
rocfl ls -l
Adding the -p
flag additionally provides the path from the storage root to the object:
rocfl ls -lp
A subset of objects can be listed by providing a glob pattern to match on:
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:
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:
rocfl ls -l foobar
The -p
flag can also be used here to display the paths to the physical files on disk:
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:
rocfl ls -v1 foobar
An object's contents can be filtered by specifying a glob pattern to match on:
rocfl ls foobar '*.txt'
The output is sorted by name by default, but can also be sorted version or updated date:
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:
rocfl log foobar
Only display the five most recent versions:
rocfl log -rn5 foobar
Show all of the versions, but formatted so each version is on a single line:
rocfl log -c foobar
Show all of the versions that affected a specific file:
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:
rocfl show foobar
Show the changes in the first version:
rocfl show foobar v1
Don't show the version metadata; only show the files that changed:
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:
rocfl diff v2 v4
Cat
The cat
operation writes the contents of a file to stdout
.
Examples
Display the contents of the head version of a file:
rocfl cat foobar file1.txt
Display the contents of a file from a specific version of the object:
rocfl cat -v1 foobar file1.txt
S3
In order to interrogate a repository located in S3, you first need to create an IAM user with access to S3, and then
setup a local ~/.aws/credentials
file as described here.
Then, when you invoke rocfl
you must specify the bucket the repository is in as well as the bucket region. For example:
rocfl -R us-east-2 -b example-ocfl-repo ls
You can specify a sub directory, or prefix, that the repository is rooted in within the bucket like this:
rocfl -R us-east-2 -b example-ocfl-repo -r ocfl-root ls