A drift check answers one question: has someone changed a generated file by hand? TDK runs that check before Tilt starts, so a hand edit stops the start before anything is built. A reader asked two follow-up questions, and this article answers them from the source: what happens when the generator itself changes, and whether the check should also run before commit.
How the check decides
The check compares each generated file under .autogenerated/ with its snapshot in .autogenerated/.tdk-contract/. The snapshot is the copy TDK wrote the last time it generated that file. The comparison is a byte-for-byte match on the file contents.
Only one kind of difference counts as drift. If a generated file differs from its snapshot, it was edited by hand, and tdk up stops and lists it. The fix the message offers is tdk config regenerate to discard the edits, or tdk up --ignore-drift to skip the check.
A different kind of difference is not drift. If service.json changed since the outputs were written, the outputs are stale, and tdk up regenerates them. That is the normal edit-then-start loop.
The service.yaml file is exempt. It is a runtime projection with timestamps, so it has no snapshot to compare.
Does a generator change look like drift?
The question is whether a legitimate change to a template or generator is flagged. From the code, the answer is no, and the reason is worth understanding.
The check has no notion of a generator version. It never asks which generator produced a file. It only asks whether the file on disk matches the snapshot written at the last generation. If the generator changed, the new output and the new snapshot are written together, so they still match. The check passes.
I did not run this against a real generator change, so treat it as a reading of the code rather than a tested result. It has one consequence worth knowing. A file that an older generator wrote still matches its snapshot, so the check passes even though the current generator would produce something different. Staleness is invisible to this check. Only a hand edit, which differs from the snapshot, is flagged.
What this means in practice: upgrading TDK does not raise a false alarm. Equally, the check does not warn you that a generator upgrade changed your output. Review the diff after an upgrade, the same way you would review any dependency change.
Fail fast, and why it matters
Running the check before Tilt starts is the design choice a reader praised, and it is worth stating why. A check after the build finds the problem minutes later, after images have been built with the edited file. Checking first costs nothing and points at the file.
Should it run before commit?
The reader suggested a pre-commit check, so that a hand-edited generated file never reaches git. That is a sound idea, and TDK already has the pieces.
tdk config verify checks the wider generated project and compares the generated service files with their snapshots. tdk doctor covers local readiness and discovered service problems. The repo's contributor guidance keeps those two distinct, so a pre-commit hook should call tdk config verify, not tdk doctor, when it is checking generated files.
Two things to settle first:
-
Whether generated files are committed. If
.autogenerated/is ignored by git, a hand edit never reaches the repository, and the pre-commit check guards only your local copy. Check your.gitignorebefore you decide. - Whether snapshots are committed. The snapshots must travel with the project for a teammate's check to mean anything.
A sketch of the pre-commit step
tdk config verify
Run it from the project root in a git pre-commit hook, and make it fail the commit when it exits non-zero. Keep the hook fast, since it runs on every commit.
Summary
The drift check compares each generated file with the snapshot from its last generation. It blocks a start on a hand edit, not on a stale output. It does not flag a legitimate generator change, and it cannot see that an output is stale after a generator upgrade, so review generator upgrades yourself. Before commit, tdk config verify is the right command to call, and the first question to answer is whether your generated files are committed at all.
