1.0.0-rc.7
Pre-release
cloudflare/artifact-fs1.0.0-rc.7Jul 26, 2026by elithrar
AI Summary
Improves handling for remotes without blob filter support and updates CLI for source selection.
Key Highlights
- Use `--depth 1` for remotes lacking blob filter support
- CLI changes: `--ref` preferred over deprecated `--branch`
- Status output changes to include verified-source provenance
Breaking Changes
- CLI changes: `--branch` is deprecated in favor of `--ref`
- Status output format changes to include source, verification, and policy details
- Ref presentation changes to store refs canonically
New Features
- Shallow source acquisition with `--depth 1`
- Canonical ref selection
- Verified source provenance
- Linux FUSE E2E coverage
Full Release Notes
This release improves handling for remotes that do not support blob `filter` operations. Instead of allowing the Git filter fallback to clone the complete ref history, pass `--depth 1` to limit acquisition to the selected revision. The blobs for the selected revision still download eagerly when the remote lacks filter support.
## CLI changes
- **Source selection:** Prefer canonical refs with `--ref`; `--branch` remains a deprecated compatibility alias.
```sh
# Before - Select and track a branch by its short name.
artifact-fs add-repo \
--name workers-sdk \
--remote https://github.com/cloudflare/workers-sdk.git \
--branch main
# After - Select an explicit canonical source ref.
artifact-fs add-repo \
--name workers-sdk \
--remote https://github.com/cloudflare/workers-sdk.git \
--ref refs/heads/main
```
- **Status output:** Keep the existing `head` and `ref` fields while exposing verified-source provenance and policy.
```sh
# Before - Report the current commit and tracked branch.
artifact-fs status --name workers-sdk
# repo=workers-sdk state=mounted head=<commit> ref=main ...
# After - Preserve head/ref and add source, verification, base, and refresh details.
artifact-fs status --name workers-sdk
# repo=workers-sdk state=mounted head=<commit> ref=main source_ref=refs/heads/main required_commit=none acquisition=not_required base_commit=<commit> remote_refresh=enabled ...
```
- **Ref presentation:** Store refs canonically without changing the familiar short branch shown by `list-repos`.
```sh
# Before - Store and display the short branch name.
artifact-fs add-repo --name workers-sdk --remote https://github.com/cloudflare/workers-sdk.git --branch main
artifact-fs list-repos
# workers-sdk main ...
# After - Store refs/heads/main, keep list-repos short, and expose the canonical ref in status.
artifact-fs add-repo --name workers-sdk --remote https://github.com/cloudflare/workers-sdk.git --ref refs/heads/main
artifact-fs list-repos
# workers-sdk main ...
artifact-fs status --name workers-sdk
# repo=workers-sdk ... source_ref=refs/heads/main ...
```
## Notes
- Adds verified shallow source acquisition with `--require-commit`, `--depth`, and `--refresh never`; `--depth 1` prevents a blob-filter fallback from transferring the full ref history, while the selected revision blobs still download eagerly when filtering is unsupported.
- Fetches canonical refs into a private candidate and atomically installs only a validated Git directory, reacquiring when persisted evidence exists but the local Git directory is unavailable.
- Pins the verified commit as the published base while retaining writable overlays and lazy blob hydration; required-commit repositories do not adopt later local HEAD changes.
- Persists acquisition evidence in status and adds Linux FUSE E2E coverage for hydration, overlay writes, disabled refresh and watcher behavior, restart recovery, and mounted status.