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 statusdoes 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>andgit worktree add -b <branch> <path> <commit>, from the same base worktree. Each run then read the disk, rangit status --porcelain=v1twice, and removed the worktree withslimtree rm <path>orgit worktree remove <path>. - The first
git statusran 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 withoutUSE_NSECdoes, so a gap over 1 s puts the firstgit status's index write in a later second than every file the create wrote. git's secondgit statusthen 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.ducounts 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 status38 ms and 196 ms, secondgit status31 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
lstatpasses 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 statustook 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>andgit worktree add -b <branch> <path> <commit>, from the same base worktree. Each run then waited 2 s, rangit status --porcelain=v1twice, and removed the worktree withslimtree rm <path>orgit worktree remove <path>. - The wait is for Git, which on this machine compares file times in whole
seconds, as a Git built without
USE_NSECdoes. A file whose mtime shares the second in which Git last wrote the index is racily clean, and everygit statushashes it again until one writes the index in a later second. Without the wait, the firstgit statuscould write the index in the same second asgit worktree addwrote its files, and git's secondgit statusthen took up to 433 ms. With the wait, as when a person runsgit statusseconds after making a worktree, git's secondgit statustook between 9.3 ms and 10.8 ms in every round. - git's first
git statusstill hashes the filesgit worktree addwrote 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 firstgit statustook 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
ducounts 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, soducounts git's checkout in full. - The first
git statushydrated 2 blobs, the root's.gitignoreand.gitattributes. They hold 4,272 bytes;duof 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 secondgit statushydrated none. slimtree newcopies 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 rmdeletes the copy once no worktree uses it, so after a home's last worktree goes, the nextslimtree newcopies 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 listwith and without that summary, median of 20 pairs at a load average of 1.9. slimtree rmleaves a 0.88 MiB archive of the worktree's state, whichslimtree prunedeletes 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 status133 ms and 489 ms, secondgit status11 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 newreturned. 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,awaitMountreads the daemon's status each time the daemon writes it, then checks the mount withgit rev-parse, andslimtree newwrites 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/loginmakes~/wt/logininstead.slimtree new spike --from origin/mainmakes~/src/app-spikeon a new branchspikeatorigin/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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 glibc 2.17+ ARM64, Linux musl 1.1+ 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 logRelease 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 logRelease 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 logSecurity 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.
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 logA 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.