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.