Earthly cache works similarly to Dockerfile layer-based caching. In fact, the same technology is used underneath.
Many Earthfile commands create cache layers. A cache layer may be reused in a future build, if the conditions under which it is created are the same.
Examples of commands which create layers are
One of the main things influencing the conditions are "sources". Sources are created through commands like
RUN, however, is not a source, even if the command itself involves downloading content from an external location. This means that a
RUN command, on its own, would always be cached if it has been run under the same circumstances previously (except for the
RUN --push variant).
For a primer into Dockerfile caching see this article. The same principles apply to Earthfiles.
Earthly cache is persisted in a docker volume called
earthly-cache on your system. When Earthly starts for the first time, it brings up a BuildKit daemon in a Docker container, which initializes the
earthly-cache volume. The volume is managed by Earthly's BuildKit daemon and there is a regular garbage-collection for old cache.
The default cache size is adaptible depending on available space on your system. If you would like to limit the cache size more aggressively, you can specify a different limit by modifying the
cache_size_mb setting in the configuration. For example:
The cache can be safely deleted manually, if the daemon is not running
docker stop earthly-buildkitddocker rm earthly-buildkitddocker volume rm earthly-cache
However, it is easier to simply use the command
earth prune --reset
which restarts the daemon and resets the contents of the cache volume.