rocfl

rocfl 是一个用于与本地文件系统或 S3 上的 OCFL 存储库交互的命令行工具。它的目标是提供一个 OCFL 对象的逻辑视图，并使它们以类 Unix 的方式易于交互。

rocfl 支持 OCFL 规范版本 1.0 和 1.1。

扩展支持

rocfl 支持以下扩展

• 0001-digest-algorithms
• 0002-flat-direct-storage-layout
• 0003-hash-and-id-n-tuple-storage-layout
• 0004-hashed-n-tuple-storage-layout
• 0005-mutable-head: 仅支持读取；不支持写入。
• 0006-flat-omit-prefix-storage-layout
• 0007-n-tuple-omit-prefix-storage-layout

此外，它还使用以下扩展进行写入支持，这些扩展尚未指定

• rocfl-staging: 默认情况下，新对象版本在此扩展的目录中进行暂存，其内容类似于 OCFL 仓库。
• rocfl-locks: 此扩展包含对象文件锁，提供有限的并发修改保护。

安装

在 发布页面 上有预构建的二进制文件，应该适用于大多数常见的操作系统和架构。您不需要安装 Rust 就可以使用它们。

1. 下载并解压相应的二进制文件
2. 执行 ./rocfl help 以验证其是否正常工作

本地构建

或者，您可以根据以下说明从源代码构建 rocfl

1. 安装 Rust，并确保 cargo 在您的 PATH 中
2. 执行： cargo install rocfl
3. 验证安装： rocfl help

如果您想构建一个不包含 S3 集成的二进制文件，该集成添加了大量的依赖项，则可以通过运行以下命令完成： cargo install rocfl --no-default-features。

配置

rocfl支持可选配置，使其使用起来更加简洁。rocfl期望在以下，与操作系统相关的位置找到其配置文件：

• Linux：$HOME/.config/rocfl/config.toml
• Mac：$HOME/Library/Application Support/org.rocfl.rocfl/config.toml
• Windows：{FOLDERID_RoamingAppData}/rocfl/rocfl/config/config.toml

您可以通过执行rocfl config轻松编辑配置，这将创建/打开配置文件以进行编辑。

配置文件可以包含任意数量的部分，其结构如下：

[repo-name]
# The name to attribute new OCFL versions to
author_name = "My Name"
# The URI address to associate with the above name
author_address = "mailto:[email protected]"
# The absolute path to the OCFL storage root
root = "/path/to/storage/root"
# The absolute path to the OCFL staging root
staging_root = "/path/to/staging/root"

# The next properties only apply when using S3
# The AWS region your bucket is in
region = "aws-region"
# The AWS credentials profile to load credentials from. If not specified, "default" is used.
profile = "aws-credentials-profile"
# The URL to the S3 endpoint. This is only needed if you are using a non-standard region
endpoint = "https://s3-endpoint"
# The S3 bucket the OCFL repository is in
bucket = "s3-bucket"

repo-name是分配给配置的任意名称。这是您在调用--name选项时传递给rocfl的值。

可以使用特殊的[global]部分来为所有配置提供默认值。这主要用于定义author_name和author_address。

所有这些属性都对应于可以指定给rocfl的参数。首先加载global配置，然后覆盖特定存储库的配置，最后应用直接作为命令行参数指定的任何值，以解析配置。

有关配置属性的更多信息，请参阅命令行参数文档。

用法

以下是对rocfl支持的特性的概述。有关所有可用选项的详细描述，请通过执行rocfl help或rocfl help <COMMAND>来咨询内置的帮助。

读取命令

验证

使用validate命令可以验证整个OCFL存储库或存储库中的特定对象。任何识别出的问题都会与其相应的验证代码一起报告。

示例

验证整个存储库

rocfl validate

验证整个存储库，不执行内容完整性检查，仅报告错误

rocfl validate -n -l Error

验证整个存储库并抑制警告W004

rocfl validate -w W004

验证特定对象

rocfl validate urn:example:rocfl:object-1

验证相对于存储库根目录的特定路径上的多个对象

rocfl validate -p object-1/ object-2/

列出

ls命令可以列出存储库中的所有对象或列出OCFL对象中的文件。

只要不需要对对象进行排序或以格式化的表格显示，ls就会列出找到的对象。默认情况下，对象列表不排序，可以通过-t禁用格式化的表格。

由于rocfl必须扫描存储库以定位对象，因此当操作大型存储库时，这可能很慢。如果存储库使用定义在存储库的ocfl_layout.json中的受支持存储布局扩展，则可以避免扫描以列出对象的目录。

列出文件时，仅返回最新版本的文件。可以使用-v选项查询先前版本。

示例

列出对象

以下命令列出当前工作目录根目录中存储库的所有对象ID

rocfl ls

此命令列出相同的对象，但包含更多详细信息，包括当前版本和更新日期

rocfl ls -l

添加-p标志将提供从存储根到对象的路径

rocfl ls -lp

可以通过提供匹配的glob模式来列出对象子集

rocfl ls -lo '*object*'

列出对象内容

通过在特定对象ID上调用 ls，可以显示对象当前状态的内容

rocfl ls urn:example:rocfl:object-1

使用 -l 标志，可以显示更多详细信息。在这种情况下，版本和日期指示了单个文件最后一次更新的时间

rocfl ls -l urn:example:rocfl:object-1

可以使用 -p 标志在这里显示相对于存储根的物理文件路径

rocfl ls -p urn:example:rocfl:object-1

通过使用 -v 选项，可以显示以前版本的内容。以下命令显示了对象第一个版本中的文件

rocfl ls -v1 urn:example:rocfl:object-1

可以通过指定匹配的glob模式来过滤对象的内容

rocfl ls urn:example:rocfl:object-1 '*.txt'

默认按名称排序输出，但也可以按版本或更新日期排序

rocfl ls -l -s version urn:example:rocfl:object-1

使用 -D 标志可以将对象内的路径解释为包含逻辑目录。例如，以下将列出逻辑目录 sub/dir 的直接子逻辑文件和逻辑目录

rocfl ls -D urn:example:rocfl:object-1 sub/dir

日志

log 命令显示对象所有版本的版本元数据。它还可以在对象内的文件上执行，在这种情况下，只显示影响指定文件的版本。

示例

以升序显示对象的全部版本

rocfl log urn:example:rocfl:object-1

只显示最近的五个版本

rocfl log -rn5 urn:example:rocfl:object-1

以单行格式显示全部版本

rocfl log -c urn:example:rocfl:object-1

显示影响特定文件的全部版本

rocfl log urn:example:rocfl:object-1 file1.txt

显示

show 命令显示在特定版本内对象中发生的变化。如果没有指定版本，则显示最近的更改。

示例

显示最新版本中的更改

rocfl show urn:example:rocfl:object-1

显示第一个版本中的更改

rocfl show urn:example:rocfl:object-1 v1

不显示版本元数据；只显示已更改的文件

rocfl show -m urn:example:rocfl:object-1

Diff

diff 命令显示两个特定版本之间的更改文件。

示例

显示第二个和第四个版本之间的更改

rocfl diff v2 v4

Cat

cat 命令将文件的內容写入 stdout。

示例

显示文件头版本的內容

rocfl cat urn:example:rocfl:object-1 file1.txt

显示对象特定版本中的文件內容

rocfl cat -v1 urn:example:rocfl:object-1 file1.txt

状态

status 命令显示具有挂起的提交更改的对象，以及对象的挂起更改。

示例

列出所有具有挂起更改的对象

rocfl status

列出对象的所有文件级别更改

rocfl status urn:example:rocfl:object-1

可以使用具有更多功能的 ls、show 和 cat 命令来检查挂起更改，方法是添加 -S 标志。

信息

info 命令显示有关存储库和对象的信息，例如版本规范和配置的扩展。

示例

显示存储库的信息

rocfl info

显示对象的信息

rocfl info urn:example:rocfl:object-1

写命令

rocfl 通过在本地挂起存储库中对对象进行更改来支持通过更新OCFL对象。对于基于文件系统的存储库，挂起存储库位于存储根的扩展目录中，对于S3则位于用户的家庭应用程序数据中。

预期的流程是累积对象的一系列更新，然后提交所有更改以创建一个新的OCFL版本。

Init

init 命令用于创建新的 OCFL 仓库。默认情况下，使用最新的 OCFL 规范版本以及 0004-hashed-n-tuple-storage-layout 存储布局。

示例

使用默认布局 0004-hashed-n-tuple-storage-layout 创建新的仓库

rocfl -r /var/tmp/ocfl-repo-1 init

可以通过传递包含所需配置的配置文件来更改默认布局配置

rocfl -r /var/tmp/ocfl-repo-2 init -l 0003-hash-and-id-n-tuple-storage-layout -c
my-config.json

新

new 命令将新的 OCFL 对象放入暂存状态。新对象只有在提交后才会存在于主仓库中。如果没有指定选项，将使用 OCFL 规范推荐的所有值创建对象。

示例

使用非标准设置创建新对象

rocfl new urn:example:rocfl:object-1 -d sha256 -c data -z 6

复制

cp 命令将文件从本地文件系统复制到暂存对象中，或将对象内的逻辑路径复制到对象内的同一位置的新位置。此命令尽可能模仿 GNU cp 的行为。

示例

将目录复制到对象的根目录

rocfl cp -r urn:example:rocfl:object-1 /path/to/src -- /

将多个文件复制到对象内的逻辑目录中

rocfl cp urn:example:rocfl:object-1 /path/to/files/* -- sub/dir

将多个现有文件内部复制到新位置

rocfl cp -i urn:example:rocfl:object-1 'internal/*.txt' -- new-location

将整个逻辑目录从旧版本复制到暂存版本的新位置

rocfl cp -ir -v2 urn:example:rocfl:object-1 src/dir -- dst/dir

移动

mv 命令将文件从本地文件系统移动到暂存对象中，或将对象内的逻辑路径移动到对象内的同一位置的新位置。此命令尽可能模仿 GNU mv 的行为。

示例

将目录移动到对象的根目录

rocfl mv urn:example:rocfl:object-1 /path/to/src -- /

将多个文件移动到对象内的逻辑目录中

rocfl mv urn:example:rocfl:object-1 /path/to/files/* -- sub/dir

将现有文件内部移动到新位置

rocfl mv -i urn:example:rocfl:object-1 internal/file.txt -- new/location.txt

删除

rm 命令从对象中删除文件。如果被删除的文件是新添加到暂存版本的，则它们将被永久删除，不会出现在对象的任何位置。否则，将删除暂存版本中对文件的引用，但这些文件仍然存在于早期版本中。

示例

递归删除逻辑目录

rocfl rm -r urn:example:rocfl:object-1 path/to/dir

删除多个单个文件

rocfl rm urn:example:rocfl:object-1 path/to/file1.txt path/to/file2.txt

或使用 glob

rocfl rm urn:example:rocfl:object-1 'path/to/*.txt'

重置

reset 命令取消对对象的更改。删除的文件将被移除，被删除或修改的文件将恢复到其以前的状态。

示例

将文件重置为其以前的状态

rocfl reset urn:example:rocfl:object-1 file.txt

将整个对象重置为其以前的状态，删除所有暂存更改

rocfl reset urn:example:rocfl:object-1

提交

commit 命令将对象的暂存更改移动到 OCFL 对象作为新版本。

示例

将对象更改提交

rocfl commit urn:example:rocfl:object-1 -n "My Name" -a "mailto:[email protected]" -m "commit
message"

如果您在 rocfl 配置 中定义了您的姓名和地址，则可以简化此过程。在这种情况下，您只需执行以下操作

rocfl commit urn:example:rocfl:object-1 -m "commit message"

您的姓名和地址将自动添加到版本元数据中。

为了将对象提交到未定义存储布局的仓库，必须手动指定存储对象的位置，如下所示

rocfl commit urn:example:rocfl:object-1 -m "commit message" -r relative/path/to/object/root

清除

purge 命令永久从主 OCFL 仓库中删除对象。这不是一个暂存更改的操作。但是，在删除对象之前会要求确认。

升级

upgrade 命令将对象或仓库升级到较新的 OCFL 规范版本。当仓库升级时，OCFL 对象不会自动升级，必须单独升级。升级 OCFL 对象需要创建新的对象版本，并且对对象的暂存更改将包含在升级版本中。

示例

将 1.0 仓库升级到规范版本 1.1

rocfl upgrade -v 1.1

将对象升级到规范版本1.1

rocfl upgrade urn:example:rocfl:object-1 -n "My Name" -a "mailto:[email protected]" -m "upgrade to 1.1"

S3

S3配置

要连接到S3中的OCFL存储库，您首先需要创建一个具有S3桶访问权限的IAM用户，然后设置一个本地的~/.aws/credentials文件或环境变量，如下所述这里。可以使用--profile选项指定凭证配置文件。然后，当您调用rocfl时，必须指定存储库所在的桶以及桶所在的区域。例如

rocfl -R us-east-2 -b example-ocfl-repo ls

您可以通过以下方式指定存储库根目录所在的子目录或前缀

rocfl -R us-east-2 -b example-ocfl-repo -r ocfl-root ls

对象的更改在本地进行暂存，并且只有在暂存版本提交时才会推送到S3。默认情况下，更改在以下位置进行暂存

• Linux：$HOME/.local/share/rocfl/s3/staging/<sha256:BUCKET/ROOT>
• Mac：{FOLDERID_RoamingAppData}/org.rocfl.rocfl/data/s3/staging/<sha256:BUCKET/ROOT>
• Windows：$HOME/Library/Application Support/rocfl/rocfl/s3/staging/<sha256:BUCKET/ROOT>

可以通过设置--staging-root选项更改此位置。

所有这些属性都可以在rocfl的配置文件中定义，并可以通过使用配置NAME调用rocfl来激活，如下所示

rocfl -n NAME ls

重要的S3注意事项

尽管rocfl支持在S3上执行与本地文件系统相同的所有操作，但这也有一些注意事项

1. 在S3中扫描对象非常慢，使用定义的存储布局扩展对于提高性能至关重要。
2. rocfl在修改S3中的对象时没有提供任何强大的并发保证。使用文件锁来保护暂存存储库中的更改，但如果多个进程尝试从不同的暂存位置提交对同一对象的更改，则存在未检查的竞争条件。

路线图

以下功能是计划中的

1. 将对象导出到存储库外的位置
2. 当存储布局未知时索引对象
3. 不安全的变更操作，如squash、revert和rewrite，这些操作可以用于更改对象的历史记录