Watch Files for Build Commands

Watch Files allow you to configure build commands so they only run when specific files have changed between deployments. This can save significant build time and resources when deployments only affect unrelated parts of your codebase.

How it works

When you add file patterns to the Watch Files field on a build command, DeployHQ will compare the files that changed between the start and end revisions of each deployment. If none of the changed files match any of the watch patterns, the build command is skipped entirely and will not appear in your deployment log.

Build commands without any watch files configured will always run, preserving existing behavior.

Configuring Watch Files

In the DeployHQ UI

Navigate to your project's Build Pipeline page, then create or edit a build command. You will see a Watch Files field below the command input.

Enter a comma-separated list of file patterns:

package.json, package-lock.json, src/**/*.js

In .deploybuild.yaml

You can also configure watch files in your .deploybuild.yaml file by adding a watch_files array to any build command entry:

build_commands:
  - description: "NPM Build"
    command: "npm ci && npm run build"
    halt_on_error: true
    watch_files:
      - "package.json"
      - "package-lock.json"
      - "src/**/*.js"
      - "src/**/*.jsx"

  - description: "Composer Install"
    command: "composer install --no-dev"
    halt_on_error: true
    watch_files:
      - "composer.json"
      - "composer.lock"

Via the API

The watch_files field is available as a string parameter when creating or updating build commands through the API:

{
  "build_command": {
    "description": "NPM Build",
    "command": "npm ci && npm run build",
    "halt_on_error": true,
    "watch_files": "package.json, package-lock.json, src/**/*.js"
  }
}

Supported patterns

Watch files supports glob patterns using the same syntax as .deployignore files:

Note that * only matches within a single directory level, while ** matches across multiple directory levels.

Important considerations

First deployments: On the very first deployment for a project (where there is no previous revision to compare against), all build commands will run regardless of watch file settings.

Full deployments: Watch file filtering uses the same revision comparison as normal deployments. If you trigger a full deployment, the changed file list is still based on the difference between the start and end revisions.

Submodule changes: Files changed within Git submodules are included when evaluating watch file patterns. Submodule file paths are prefixed with the submodule directory, for example vendor/lib/utils.js.

Templates: Watch file settings are preserved when applying a template to a new project.

Warning: not recommended for most workflows

For the majority of use cases, we recommend keeping build commands simple and letting them run on every deployment. Watch files add complexity and can lead to subtle issues:

• If your build output depends on files you did not include in the watch list, deployments may upload stale assets.
• Changes to environment variables, language versions, or build configuration do not trigger watch file matches, since these are not repository file changes.
• If a previous deployment failed partway through, a subsequent deployment that skips the build command may not produce the expected output.

Watch files are best suited for projects with clearly separated build steps where you are confident about which files affect each command. If you are unsure, leave the watch files field empty to ensure your build commands always run.

Visibility in deployment logs

When a build command is skipped due to watch file filtering, it will not appear as a step in your deployment log. This is by design -- skipped commands do not consume build time and are excluded from the deployment pipeline entirely. If you expected a command to run and it did not, check the watch file patterns to ensure they cover all relevant files.