| name | artifact-fs |
| description | Mounts Git remotes with ArtifactFS as local working trees without a full clone. Use when asked to mount a remote repo, explain committed state versus dirty overlay state, or mount multiple repos under one daemon. Use when this capability is needed. |
| metadata | {"author":"cloudflare"} |
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
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
Source: cloudflare/artifact-fs — distributed by TomeVault.
