Excluded Files

Excluded files in DeployHQ are files that you need to store in your repository, or that might be generated within a build pipeline but not uploaded to your server.

To add an excluded file, head to your project's Settings dropdown, then the Excluded Files option. Click to add a new excluded file, entering the full path of the file as it's stored in the repository (not as it's placed on the server) as the name, or one of the standard recipes if you want to exclude directories or specific file types.

If you want to exclude files for certain server environments in your project, uncheck the Exclude this file on all current and future servers? option and select individual servers.

Common Recipes

Some working examples of file exclusion rules might look like so:

Basic Directory Exclusions

• vendor - Only your vendor directory will be excluded, anything inside vendor will still be uploaded
• vendor/** - All files and subdirectories within your vendor directory will be excluded from deployments, the vendor folder itself will still be uploaded.
• node_modules - Only your node_modules directory will be excluded, anything inside node_modules will still be uploaded
• node_modules/** - All files and subdirectories within your node_modules directory will be excluded from deployments, the node_modules folder itself will still be uploaded.

As per the examples above, you will always need to add two rules to exclude a folder, as well as its contents.

Make sure the plain directory rule does not end with a trailing slash, otherwise it will not match the directory entry that DeployHQ generates in the manifest. If you only add a rule for a directory's contents (for example deploy/public_html/resources/**), DeployHQ still treats the directory entry itself as a change, so it will continue to appear in the deployment preview even though the files are skipped. Add the explicit directory rule alongside the recursive rule so that everything is ignored:

deploy/public_html/resources
deploy/public_html/resources/**

Remember that * only matches the immediate files in a directory, whereas ** recurses through any nested folders.

File Type Exclusions

• **/*.yml - Any yml files will be excluded from deployments
• **/*.log - Exclude all log files anywhere in the repository
• **/*.env - Exclude all environment files
• config/*.php - All PHP files, only within your config directory will be excluded from deployments

Specific Path Exclusions

• /readme/ - Exclude the readme directory at the root of your repository
• /site/assets/files/ - Exclude a specific nested directory
• COPYRIGHT.txt - Exclude a specific file at the root
• README.md - Exclude a specific file at the root
• .env-sample - Exclude dotfiles
• .editorconfig - Exclude configuration files

Pattern Matching Examples

• /site/templates/custom/default - Exclude a specific subdirectory
• /site/templates/custom/_starter - Exclude directories starting with underscore
• /site/templates/custom/ins-* - Exclude all directories starting with "ins-"
• /site/templates/custom/opt-* - Exclude all directories starting with "opt-"
• .github/ - Exclude GitHub-specific files and directories

Build Tool Exclusions

• package.json - Exclude npm package configuration
• package-lock.json - Exclude npm lock file
• .babelrc - Exclude Babel configuration
• .prettierrc.json - Exclude Prettier configuration
• .prettierignore - Exclude Prettier ignore file
• Dockerfile - Exclude Docker configuration
• .nvmrc - Exclude Node version manager configuration
• .tool-versions - Exclude version management files

Whitelisting files and directories

You can also whitelist files or directories that are within an excluded pattern.

If you're excluding everything within vendor/** for example, you might decide you want to keep one folder. Simply add the rule and prepend it with an ! symbol. It would look like this:

• !vendor/directory-to-keep/**

Files work in the same way, if you follow the above example where you're ignoring all php files in your config directory, you can allow a specific file like this:

• !config/file-to-keep.php

.deployignore

As well as adding excluded file rules in DeployHQ, you can add a .deployignore file to your repository containing rules in the exactly the same format and store it in your repository. Just add each rule on a new line, then DeployHQ will check this file and exclude any files or directories from the deployment as appropriate.

DeployHQ doesn't have support for specifying specific servers in .deployignore, therefore if you need to configure rules for certain servers, you'll need to use the Excluded Files feature in the DeployHQ interface.

Removing files already on the server

Exclusion rules - whether configured in Excluded Files or in a .deployignore file - only stop DeployHQ from uploading matching files. They do not delete files that are already on the server.

If a file was deployed previously and you later add it to your exclusion rules, the next deployment will skip uploading it, but the existing copy on your server will remain in place until you remove it manually (for example via an SSH command).

Interaction with zero-downtime deployments

This becomes a common source of confusion on zero-downtime servers using the Copy previous release before uploading changes to new release strategy. Because each new release is built by first cloning the previous release directory, any file present in the previous release is carried into the new one - even if it is now matched by an exclusion rule. The file is not re-uploaded, but it is still copied across, so from outside it looks as though the exclusion is being ignored.

If you need a file to disappear from new releases on a zero-downtime server with that strategy, do one of the following:

• Switch the server's atomic strategy to Upload changes to a cache directory and copy new release from there. The cache contains only repository contents, so excluded files are never carried forward.
• Run a deployment from scratch so the next release starts clean.
• Add an SSH command to rm the file from the new release path (for example rm -f %release_path%/path/to/file).

Viewing Excluded Files in Deployment Reports

When you run a deployment, you can see which files were excluded in the deployment report. To view the deployment report:

1. Navigate to your project's deployments page
2. Click on a completed deployment
3. View the deployment report which shows all steps

During the "Generate Manifest" step of the deployment, DeployHQ will log a list of files that were excluded. For example, if you have excluded files, you'll see a log entry like:

Excluded files for server 'Production Server'

  - README.md
  - node_modules/package.json
  - vendor/bundle/gem.rb
  - docs/guide.md
  - docs/api.md

This helps you verify that your exclusion rules are working as expected and gives you visibility into which files are being filtered out of your deployments.