Better documentation for auto-prune semantics

[andrewhamon]

In the help text of tart clone, you will find this:

Due to copy-on-write magic in Apple File System, a cloned VM won't actually claim all the space right away.
Only changes to a cloned disk will be written and claim new space. By default, Tart checks available capacity
in Tart's home directory and checks if there is enough space for the worst possible scenario: when the whole disk
will be modified.

This behaviour can be disabled by setting TART_NO_AUTO_PRUNE environment variable. This might be helpful
for use cases when the original image is very big and a workload is known to only modify a fraction of the cloned disk.

This is confusing in several ways:

• the first paragraph doesn't describe pruning at all, it just describes a safety check that could exist independently of auto-prune (does it? I don't think so, i think it is coupled to auto-prune)
• the second paragraph says you can disable that behavior with TART_NO_AUTO_PRUNE - but again, there has been no mention of pruning at all at this point.
• I can't find a description of what exactly auto-prune does

What I have noticed, though, is that once I run out of space, all my cached OCIs and IPSWs are lost. In my case, all my VMs are ephemeral, so it is much more annoying to prune OCIs (which I will have to re-download) than it is to prune VMs. I understand why OCIs are purged first - that seems like a safer default.

For me, ideally, I would like to disable auto-pruning while preserving the free-space safety check.

[fkorotkov]

Pruning might be a bit aggressive in case your image disk's size is 30+% of the host disk. Auto-pruning is a bit aggressive:

Tart checks available capacity in Tart's home directory and checks if there is enough space for the worst possible scenario: when the whole disk will be modified.

Meaning that if you have 200GB image on a host with 512GB SSD. Then if you'll clone this image twice than auto-pruning will clean up OCI cache. If you are certain in what you do, you can try to disable pruning via TART_NO_AUTO_PRUNE and manually run something like tart prune --space-budget 50 before each clone to make sure you image will always have 50GB of space for builds.

[ethaniel86]

i can't even find the official documentation link page lol

[edigaryev]

This is now documented on tart.run website.