Skip to main content

This repository is a fork of cloudflare/artifact-fs. artifact-fs's docs are in docs/artifact-fs.md.

slimtree

slimtree makes git worktrees that take little disk. On macOS it clones the files of an existing worktree of the repository with APFS clones, which share their blocks with the originals until either side changes a file. Git sees an ordinary worktree, so git status, commits and branches work as they do after git worktree add. On Linux it serves each worktree from an artifact-fs FUSE mount, which reads file contents from Git's objects as they are needed.

Measured

A new worktree of pydantic-ai (6,069 tracked paths, 333 MiB), median of 5 rounds.

macOS

slimtree git worktree add
Disk, at the base worktree's commit 0.84 MiB 346 MiB
Disk, at a pull request's commit 2.07 MiB 346 MiB
Create 1.10 s 1.49 s
First git status 35 ms 453 ms
Second git status 33 ms 29 ms
Remove 0.39 s 0.33 s

slimtree saves disk and, by median, makes a worktree faster than git. It clones the base worktree's files instead of writing them, and records each clone's stat data in the new worktree's index, so its first git status hashes no clone: it took 35 ms against its second's 33 ms at the base worktree's commit, and 38 ms against 31 ms at the pull request's. Create plus first git status takes 1.16 s against git's 1.85 s at the base worktree's commit, and 1.17 s against 1.42 s at the pull request's. Remove takes longer: slimtree rm archives the worktree's record and keeps a recovery ref of its HEAD before it removes the worktree.

slimtree checks no clone byte for byte against its blob. It trusts a clone only when all of these hold:

  • the base's git status does not list the file, and the base's HEAD has the same mode and blob there as the new worktree's commit;
  • slimtree did not rewrite the clone from Git;
  • the base's index does not mark the path assume-unchanged or skip-worktree;
  • the base's attributes convert nothing for the path;
  • the clone is a regular file of its blob's size;
  • its mtime is older than the second in which slimtree read the base's HEAD;
  • the base's HEAD is the same commit when slimtree registers the worktree.

So the trust is only as good as the base's own git status: its index's stat data, core.checkStat, core.trustctime and its fsmonitor.

How it was measured:

  • slimtree --version: slimtree dev (untagged, e5fed326a40c, go1.27.4, darwin/arm64), built from main e5fed32 as the release workflow builds it (CGO_ENABLED=0 go build -trimpath -ldflags "-s -w"), without its version stamp.
  • Both tools made a new branch: slimtree new <branch> --from <commit> --path <path> and git worktree add -b <branch> <path> <commit>, from the same base worktree. Each run then read the disk, ran git status --porcelain=v1 twice, and removed the worktree with slimtree rm <path> or git worktree remove <path>.
  • The first git status ran between 2.0 s and 15.3 s after the create. The disk readings fill that gap. In 9 of the 20 runs they took less than 2 s, and the run waited out the rest. Git here compares file times in whole seconds, as a Git built without USE_NSEC does, so a gap over 1 s puts the first git status's index write in a later second than every file the create wrote. git's second git status then took between 28 ms and 47 ms in every round.
  • Disk is the data only the new worktree and its admin directory hold: the sum of APFS's private size (ATTR_CMNEXT_PRIVATESIZE) over their files, read right after the create. du counts a clone's shared blocks, so it reports 345 MiB for either tool. The pull request's commit differs from the base worktree's in 56 paths.
  • Times are the wall-clock time of each command, at the base worktree's commit. At the pull request's commit they were: create 1.14 s and 1.21 s, first git status 38 ms and 196 ms, second git status 31 ms and 28 ms, remove 0.40 s and 0.35 s, for slimtree and git.
  • Create took between 1.04 s and 1.32 s for slimtree and between 1.17 s and 2.75 s for git at the base worktree's commit, and between 1.03 s and 4.73 s and between 1.12 s and 1.48 s at the pull request's. There, two of slimtree's five creates, 1.78 s and 4.73 s, took longer than git's slowest.
  • Traces of 10 more slimtree creates at the pull request's commit show that refresh hashed no file in any of them. The slow ones spent their time in slimtree's clone and lstat passes and in git's own commands. The slowest traced create ran at a 1-minute load of 20.5 to 29.5, and every one of its steps slowed. Memory pressure on the machine is a likely cause, but the runs recorded no memory data, and the 4.73 s round itself has no trace.
  • git's first git status took between 154 ms and 960 ms at the base worktree's commit, and between 79 ms and 506 ms at the pull request's. slimtree's took between 32 ms and 57 ms, and between 34 ms and 47 ms, and its second between 28 ms and 37 ms, and between 29 ms and 34 ms.
  • Remove took between 0.36 s and 0.50 s for slimtree and between 0.31 s and 0.39 s for git at the base worktree's commit, and between 0.36 s and 0.52 s and between 0.33 s and 0.52 s at the pull request's.
  • The tools alternated in order each round. Every run started and ran while the 5-minute load average was under 20; it stayed between 5.9 and 7.0.
  • MacBook Air (Apple M4, 24 GB), macOS 27.2, internal SSD, Git 2.54.0 (Apple Git-157), 2026-11-18.

Linux

slimtree git worktree add
Disk, at the base worktree's commit 3.51 MiB 348 MiB
Disk, at a pull request's commit 3.51 MiB 348 MiB
Create 0.34 s 0.99 s
First git status 140 ms 476 ms
Second git status 11 ms 10 ms
Remove 0.28 s 0.13 s

On Linux slimtree saves disk, makes a worktree in about a third of git's time, and runs the first git status 3.4 times as fast as git at the base worktree's commit and 3.7 times as fast at the pull request's. Its second git status is within about 1.5 ms of git's. It checks out no files: the mount reads file contents from Git's objects as they are needed, and the worktree's FSMonitor hook tells git status which files changed. Remove takes longer: slimtree rm stops the daemon and archives the worktree's state before it removes the worktree.

How it was measured:

  • slimtree --version: slimtree dev (untagged, 9888021600a7, go1.27.4, linux/amd64), built from 9888021 (#129) as the release workflow builds it (CGO_ENABLED=0 go build -trimpath -ldflags "-s -w"), without its version stamp.
  • Both tools made a new branch at the macOS table's two commits: slimtree --backend artifactfs new <branch> --from <commit> --path <path> and git worktree add -b <branch> <path> <commit>, from the same base worktree. Each run then waited 2 s, ran git status --porcelain=v1 twice, and removed the worktree with slimtree rm <path> or git worktree remove <path>.
  • The wait is for Git, which on this machine compares file times in whole seconds, as a Git built without USE_NSEC does. A file whose mtime shares the second in which Git last wrote the index is racily clean, and every git status hashes it again until one writes the index in a later second. Without the wait, the first git status could write the index in the same second as git worktree add wrote its files, and git's second git status then took up to 433 ms. With the wait, as when a person runs git status seconds after making a worktree, git's second git status took between 9.3 ms and 10.8 ms in every round.
  • git's first git status still hashes the files git worktree add wrote in the second it wrote the index, and how many those are depends on where a second boundary fell during the checkout: between 862 and 5,246 of 6,057 files at the base worktree's commit, and between 716 and 3,928 of 6,069 at the pull request's. Its time rose with that number: between 116 ms and 667 ms, and between 85 ms and 608 ms. slimtree's files carry their commit's time, before the index's, so none of them is racily clean. Its first git status took between 118 ms and 157 ms, and its second between 10 ms and 13 ms.
  • The wait also slows slimtree's first git status, from 117 ms to about 140 ms, measured on a build of 059723a. slimtree and git run the same instructions at either wait, and a fixed-work program unrelated to slimtree slows the same way, so the cause is how this machine behaves after it idles. The mechanism is not confirmed.
  • Each slimtree run had its own SLIMTREE_HOME, so its blob cache started empty. The blob cache is shared, so a later worktree of the same repository reuses the blobs an earlier one hydrated.
  • Disk is what du counts right after the create. It was the same in every round: byte for byte for slimtree, within 8 KiB for git. For slimtree at the base worktree's commit: the worktree's record directory in its home (2.67 MiB, mostly the state root's databases; 2.68 MiB at the pull request's commit), its admin directory in the base's .git/worktrees (0.83 MiB), and the blob cache (0.01 MiB). The mount point is an empty directory. For git: the worktree (347 MiB) and its admin directory (0.84 MiB). ext4 shares no blocks between files, so du counts git's checkout in full.
  • The first git status hydrated 2 blobs, the root's .gitignore and .gitattributes. They hold 4,272 bytes; du of the blob cache, which also counts its shard directories, grew by 16 KiB. The slimtree worktree then took 3.56 MiB, and 3.57 MiB at the pull request's commit. The second git status hydrated none.
  • slimtree new copies its own binary (12.1 MiB) into its home when the home holds no copy of that build, and every worktree's daemon runs that copy. slimtree rm deletes the copy once no worktree uses it, so after a home's last worktree goes, the next slimtree new copies the binary again. Each home got the copy before the run, so create's time and disk leave the copy out.
  • Create's time includes the summary that slimtree prints on a home's first run: 6.1 ms (5.6 ms to 11.4 ms), the difference between slimtree --backend artifactfs list with and without that summary, median of 20 pairs at a load average of 1.9.
  • slimtree rm leaves a 0.88 MiB archive of the worktree's state, which slimtree prune deletes under the retention rule.
  • Times are the wall-clock time of each command, at the base worktree's commit. At the pull request's commit they were: create 0.34 s and 0.97 s, first git status 133 ms and 489 ms, second git status 11 ms and 10 ms, remove 0.28 s and 0.13 s, for slimtree and git.
  • Create took between 0.29 s and 0.35 s for slimtree and between 0.98 s and 1.01 s for git at the base worktree's commit, and between 0.33 s and 0.40 s and between 0.97 s and 1.00 s at the pull request's. Remove took 0.28 s in every round for slimtree at the base worktree's commit and between 0.27 s and 0.28 s at the pull request's, and between 0.13 s and 0.14 s and between 0.12 s and 0.14 s for git.
  • The daemon's log splits slimtree's create into three phases: until the daemon began to mount, the mount, and the rest until slimtree new returned. Each phase's median, so the three need not sum to create's, was 210 ms, 105 ms and 13 ms at the base worktree's commit, and 194 ms, 133 ms and 13 ms at the pull request's. In the last phase, awaitMount reads the daemon's status each time the daemon writes it, then checks the mount with git rev-parse, and slimtree new writes the worktree's record. It took between 13 ms and 15 ms at the base worktree's commit, and between 12 ms and 14 ms at the pull request's.
  • The tools alternated in order each round. Every run started and ran while the 5-minute load average was under 20; it stayed between 1.88 and 1.98.
  • AMD Ryzen 7 7700 (8 cores, 16 threads), 62 GiB, Ubuntu 26.04.1, Linux 7.0.0-43, ext4 on RAID 1 over two NVMe SSDs, fuse3 3.18.2, Git 2.53.0, 2026-11-18.

What works in this release

Command macOS on Apple silicon Linux on x86_64 or arm64
slimtree new <branch> Makes a worktree from APFS clones Makes a worktree served from an artifact-fs mount
slimtree stop <worktree> Only for --backend artifactfs Unmounts the worktree and stops its daemon; its changes stay
slimtree resume <worktree> Only for --backend artifactfs Mounts the worktree again; --all mounts every one, as after a reboot
slimtree rm <worktree> Removes an APFS clone worktree Stops the worktree's daemon, archives its files and removes it
slimtree list Lists the worktrees slimtree made Lists the worktrees slimtree made
slimtree prune Deletes the archives and recovery refs rm left that are older than the retention rule Deletes the archives and recovery refs rm left that are older than the retention rule, evicts cached blobs not read within it, and removes the daemon binary copies no worktree uses
slimtree retention [<rule>] Shows or sets how long archives are kept: week, month (the default), forever or <N>d Shows or sets the rule, which also decides how long a cached blob stays unread before prune evicts it
slimtree doctor Checks what slimtree needs Checks the FUSE setup

Release builds are tested on macOS 26, Ubuntu 24.04 and Alpine Linux. On macOS, --backend artifactfs mounts through macFUSE's FSKit backend. It is a beta, and release builds do not test it.

Install

uv tool install slimtree
slimtree doctor

slimtree doctor checks what slimtree needs on this machine and in the current directory. It installs nothing, and prints the fix for each check that fails.

Use

In a repository whose main worktree is ~/src/app:

cd ~/src/app
slimtree new fix/login    # makes ~/src/app-login on the branch fix/login
slimtree list
slimtree rm app-login

A new worktree goes next to the main worktree, named after it and the last segment of the branch: <main worktree>-<last segment>. Two variants:

  • slimtree new fix/login --path ~/wt/login makes ~/wt/login instead.
  • slimtree new spike --from origin/main makes ~/src/app-spike on a new branch spike at origin/main.

slimtree new clones the main worktree, from any worktree of the repository. It checks out the branch when it exists, and otherwise makes it at --from, else at HEAD.

On Linux, slimtree new mounts the worktree instead, and a daemon of its own serves it. Your changes live in the daemon's state under slimtree's home, and outlast slimtree stop and a reboot:

slimtree stop app-login      # unmounts it
slimtree resume app-login    # mounts it again
slimtree resume --all        # after a reboot

slimtree rm takes a worktree by its directory name or its path. It refuses a worktree with changes unless you pass --force, and slimtree rm --check runs only its checks. It keeps the worktree's HEAD in a ref under refs/slimtree/archive/ and never deletes a branch. For a worktree on an artifact-fs mount, Linux's default, it also refuses while another process works inside the mount, also with --force. It then stops the worktree's daemon, and keeps the files your changes made, with the worktree's git dir, in state.tar.gz in the archive. --exclude <glob> leaves out the files at paths with a component that the glob matches, such as --exclude node_modules. Each slimtree rm, and slimtree prune, deletes the archives and recovery refs older than the retention rule, a month by default, and evicts artifact-fs's cached blobs not read within it; slimtree retention week|month|forever|<N>d changes the rule. Run slimtree --help for every flag.

Source and license

Source: https://github.com/dsfaccini/artifact-fs. Apache-2.0; see LICENSE.

slimtree is built on dsfaccini/artifact-fs, a fork of cloudflare/artifact-fs. It is not affiliated with or endorsed by Cloudflare.

Metadata

Release files for slimtree 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for slimtree 0.3.0
File Interpreter ABI Platform Actions
slimtree-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl Python 3 none Linux musl 1.1+ x86-64, Linux glibc 2.17+ x86-64 Details for slimtree-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl
slimtree-0.3.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl Python 3 none Linux musl 1.1+ ARM64, Linux glibc 2.17+ ARM64 Details for slimtree-0.3.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl
slimtree-0.3.0-py3-none-macosx_13_0_arm64.whl Python 3 none macOS 13.0+ ARM64 Details for slimtree-0.3.0-py3-none-macosx_13_0_arm64.whl

Total release size: 15.2 MB

Release files / slimtree-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl

Download URL slimtree-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl
Size 5.3 MB
Tags Linux glibc 2.17+ x86-64 Linux musl 1.1+ x86-64 Python 3
SHA-256 checksum
How to use checksums
b8f945d24396d1118da122fa78de922a527f4064d135442660d5e7870ab7654a
BLAKE2b-256 checksum
How to use checksums
b7b388d8807201e52cc09823e6d20800cd31581cb97cf0c67e3e5b2500d5df04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / slimtree-0.3.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl

Download URL slimtree-0.3.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.musllinux_1_1_aarch64.whl
Size 4.9 MB
Tags Linux glibc 2.17+ ARM64 Linux musl 1.1+ ARM64 Python 3
SHA-256 checksum
How to use checksums
04b6e9a4d45c3fa09e927736ca69e096cdb7a54f8dacf6a68a694d5c71559528
BLAKE2b-256 checksum
How to use checksums
d07fac6651aa737dbfa42852f691e535355c3d049e25bcdb6ae916e80b58902a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / slimtree-0.3.0-py3-none-macosx_13_0_arm64.whl

Download URL slimtree-0.3.0-py3-none-macosx_13_0_arm64.whl
Size 5.0 MB
Tags Python 3 macOS 13.0+ ARM64
SHA-256 checksum
How to use checksums
1abca9443244cff6d98418008d49332036bc9c8def61d7f127746fe2a6695dd4
BLAKE2b-256 checksum
How to use checksums
6f224c2535c9a5ee51dae585e06d6dd7d34796fb3d8e78c4251cf224d2635bd9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for slimtree 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Select from 3 files

Attestation for slimtree-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.musllinux_1_1_x86_64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page