Debugging File Changes: Rebuilds and Ignores
Tilt watches your file system, and rebuilds any resources that have changed.
But what do you do when a file changes, but Tilt does the wrong thing?
This page should help you understand when file changes trigger builds, and when they don’t.
1) When Tilt builds a resource, it should print which file changes triggered that build.
2) When a file changes that you don’t have control over, Tilt should not do a rebuild.
3) We optimize the syntax so that it’s easy to ignore spurious file changes, and hard to watch too much.
Tilt will always watch the Tiltfile. If the Tiltfile changes, Tilt will re-execute it.
Most notably, this re-runs any
When it’s finished, it will diff all the
configurations, and only rebuild the ones that have changed.
How Tilt watches new files
Most Tiltfile built-in functions will automatically set up watches for the files they read. If those files change, they re-run the Tiltfile.
If your Tiltfile contains a
local() call that reads from a file,
Tilt has no way to know what file it reads. You can tell it to watch additional
files with the
When you include a
docker_build() in your Tiltfile, you give Tilt
a directory to build. Tilt will watch the entire directory.
Whenever a file in that directory changes, Tilt will re-build the image, then deploy any Kubernetes resources that depend on that image.
Custom and Local Resource Builds
When you build other types of resources (like
local_resource()), you can specify a file system path or a list of paths as
Whenever a file under that path changes, Tilt will re-run the specified scripts.
Tilt will always ignore changes under the
When you use
docker_build() in your
Tiltfile, Tilt will remove
the Docker context.
Editor temp files
Tilt has a hard-coded list of temp files in common text editors (Emacs, Vim, etc.).
As devtools developers ourselves, we want to be able to add hidden files to the repo, and not have those hidden files affect other devtools. For example, we don’t think Emacs developers wanted their temp files to break Docker caching. Lots of users get confused when this happens, because it’s not a file they control.
If you find that temp files in your editor trigger builds, please file a bug and we will add it to the list.
These temp files are still included in Docker build contexts by default.
Any docker_build commands will respect the
in their build directory. Learn more about
.dockerignore in the
docker_build commands in this directory, files that match these
patterns will not trigger rebuilds, and will be excluded from the Docker build
docker_build and ignore=
For large multi-service repos, you may have multiple
docker_build()s in the
same directory. With the
ignore= parameter, you can add image-specific ignore
For this specific
docker_build() call, files that match these patterns will
not trigger rebuilds, and will be excluded from the Docker build context.
The patterns are evaluated relative to the
context argument passed to
docker_build. For instance, given the call:
docker_build( 'image-foo', './foo', # context ignore=['bar'] )
Tilt will ignore the file
ignore= and other build types
local_resource() also support the
They handle it a a little differently than
docker_build does. See our Custom
docker_build and only=
only= parameter excludes everything but the
paths specified in
docker_build( 'image-foo', './foo', only=['./src', './static-files'])
is equivalent to having a
.dockerignore file that looks like:
** !./src !./static-files
only= parameter accepts paths, not glob patterns.
Again, these paths are evaluated relative to the
context passed to
docker_build; in the call above, the only directories included in the
resulting image are
only= and other build types
Other build types don’t have an
only= filters what files are available to the docker
build within the build context. Other types of builds are simply able to access
all files, and
deps= specifies which paths trigger them.
.tiltignore file tells Tilt about file changes that should not trigger rebuilds.
Tilt looks for a file named
.tiltignore in the same directory as your
.tiltignore patterns have the same syntax as
Learn more about
the Dockerfile reference.
Files that match these patterns will not trigger rebuilds.
.tiltignore does not affect whether a file is included in any Docker
The Tiltfile can specify additional patterns that should not trigger rebuilds.
This is equivalent to adding these patterns to
.tiltignore (correcting for any
differences in working directory). It’s useful in Tilt extensions that download
files, but that don’t want the downloaded files to trigger rebuilds as they’re
watch_settings does not affect whether a file is included in any Docker build
Try it Yourself
If you’d like to try out the APIs in this guide, see this example repo. You can:
git clone https://github.com/tilt-dev/ignore-examples
tilt upto run all the servers
- Try editing the files and see which servers reload.
If Tilt rebuilds an image, you should always be able to look at the logs and see which file change triggered that rebuild.
But there are still cases that are hard to debug:
1) If Tilt ignored a file change, which rule blocked the file? Was it a
.dockerignore or a
2) If a Docker image build wasn’t cached correctly, which file change broke the cache? Are there files in my Docker image that shouldn’t be there?
We are open to thoughts and feature requests on how to help people answer these questions!