Choose Compose Watch actions by the file change

Bottom line: Choose an update action for each kind of development change before enabling a broad watch rule. Keep source updates, dependency rebuilds and process restarts as distinct cases so a convenient editing loop does not hide a stale application state.

Source fact: documented behavior

The Use Compose Watch documentation is the primary reference.

The guide lists Compose 2.22.0 or later and describes Watch for services built from local source with build, rather than services relying on prebuilt image entries. The documented actions distinguish sync, rebuild and sync+restart: rebuilding creates a new image and replaces the service container, while synchronization with restart updates files and restarts the service. Watch requires stat, mkdir and rmdir in the image and a container user able to write the target; ignore patterns are relative to the watched path.

What the source does not establish

This article addresses a development workflow, not production deployment approval or proof that an application supports hot reload. The guide’s general minimum version is not a compatibility guarantee for every proposed configuration. Confirm the installed release, application behavior and individual rules before relying on automatic updates.

Applicability questions

• Which files should update without a process restart?
• Which changes require a rebuild or an explicit restart?
• Can the image tools and container user perform the intended synchronization?
• Which directory gives each ignore pattern its meaning?

DSE recommendation: map changes to observable actions

DSE recommends a three-case change map for the development service. Name a harmless source edit, a dependency-definition edit and a configuration edit, then have the application owner choose the intended action for each. Do not assume all files beneath one broad directory need the same response.

Review the service definition and installed Compose release against the documented workflow. Keep locally built services distinct from prebuilt-image services. Inspect the target path, configured user and required image tools before investigating application reload behavior. Avoid changing permissions broadly just to make an exploratory synchronization succeed.

Review each ignore pattern from its watched path. Identify generated or host-specific material that should remain excluded and use harmless marker files to examine the rule. Keep the application’s intended dependency management separate from a source-sync rule rather than copying a local dependency tree indiscriminately.

Write a visible acceptance observation for every action. Ask how the developer will tell that the new source is active, that a rebuild occurred or that a restart happened. Keep unexpected rebuilds and missing updates in the issue record. Make a manual approved recovery path available while the team investigates a rule instead of repeatedly saving unrelated files to provoke a response.

Verification and evidence

Proposed verification, not performed: use an isolated development stack and the three harmless edit cases from the change map. Apply one edit at a time and record the actual synchronization, restart or rebuild observation before moving to the next case.

Test an explicitly ignored marker separately and reconcile its location with the watched-path base. Retain the Compose revision, installed version, image-user check, rule, edit and actual application observation. Report only the tested cases; a responsive editor loop is not evidence that every file category or production rollout has been accepted.

Official references

• Use Compose Watch — Docker Docs.

Source review completed October 29, 2026. Recheck the official documentation and deployment-specific applicability before a production change.