Artifact Fs

ArtifactFS Usage

Use this skill to operate ArtifactFS as a consumer. Prefer the CLI workflow and mounted repos. Do not inspect ArtifactFS internals unless the task is about developing ArtifactFS itself.

FIRST: Verify Prerequisites

Run from the repo root. If either check fails, STOP and fix the environment first.

test -e /Library/Filesystems/macfuse.fs || test -e /dev/fuse
test -x ./artifact-fs || go build -o artifact-fs ./cmd/artifact-fs

Critical Rules

• Use a dedicated state root. Set ARTIFACT_FS_ROOT, usually under /tmp, so mounts and caches stay isolated.
• Prefer HTTPS remotes. For private repos, use Git credential helpers or SSH auth. Do not embed tokens or passwords in the --remote URL because --remote is a CLI arg and can show up in process listings.
• add-repo does not mount. It registers a blobless clone and exits. daemon mounts all registered repos and stays running.
• The mounted tree starts from committed Git state. Remote commits, trees, and refs are the base view. Local edits live in an overlay and appear as dirty state until committed.
• One daemon can mount many repos. Register each repo separately, then start one daemon --root <mount-root>.

Quick Reference

| Task | Command |

|------|---------|

| Register one repo | ./artifact-fs add-repo --name <name> --remote <url> --branch <branch> --mount-root /tmp |

| Mount all registered repos | ./artifact-fs daemon --root /tmp |

| Check mount and overlay state | ./artifact-fs status --name <name> |

| List registered repos | ./artifact-fs list-repos |

| Unmount or remove a repo | ./artifact-fs unmount --name <name> or ./artifact-fs remove-repo --name <name> |

Quick Start: One Repo

export ARTIFACT_FS_ROOT=/tmp/artifact-fs-demo

./artifact-fs add-repo \
  --name workers-sdk \
  --remote https://github.com/cloudflare/workers-sdk.git \
  --branch main \
  --mount-root /tmp

./artifact-fs daemon --root /tmp &
DAEMON_PID=$!

git -C /tmp/workers-sdk rev-parse HEAD
git -C /tmp/workers-sdk status
./artifact-fs status --name workers-sdk

kill $DAEMON_PID
# If a stale mount remains:
umount /tmp/workers-sdk

Mount Semantics

• Base view = branch HEAD from the blobless clone. File contents hydrate on first read.
• Dirty files are overlay state, not part of the base commit. ./artifact-fs status --name <repo> reports this as overlay_dirty=true.
• git add and git commit inside the mount are supported. After commit or checkout, the watcher re-indexes the new HEAD and reconciles stale overlay entries.

Quick Start: Multiple Repos

export ARTIFACT_FS_ROOT=/tmp/artifact-fs-demo

./artifact-fs add-repo --name repo-a --remote https://github.com/org/repo-a.git --branch main --mount-root /tmp
./artifact-fs add-repo --name repo-b --remote https://github.com/org/repo-b.git --branch main --mount-root /tmp

./artifact-fs daemon --root /tmp &
DAEMON_PID=$!

ls /tmp/repo-a
ls /tmp/repo-b
./artifact-fs list-repos

kill $DAEMON_PID
umount /tmp/repo-a
umount /tmp/repo-b