Add .deployignore support to Site Sync

[ivan-ottinger]

Related issues

• Related to STU-16

How AI was used in this PR

AI-assisted implementation with human iteration and review of all changes, architecture decisions, and edge cases. I have manually tested the changes as well.

Proposed Changes

Follow-up to #2924, which added .deployignore support for Preview Sites. This PR extends it to Site Sync (push to WordPress.com / Pressable).

• Extend createDeployIgnoreFilter to accept a basePatterns argument so the sync path can pass Studio-internal exclusions (database, db.php, debug.log, sqlite-database-integration, cache) alongside DEPLOY_IGNORE_DEFAULTS
• Sync tree UI: Update listLocalFileTree and shouldExcludeFromSync to use the deploy-ignore filter. Files matching .deployignore patterns are hidden from the sync dialog
• Sync push: CLI's DefaultExporter accepts an optional ignoreFilter in ExportOptions, used by addWpContent() alongside existing hardcoded exclusions (isExactPathExcluded, isPathExcludedByPattern). The studio export command gains a hidden --apply-deploy-ignore flag; Studio's sync push sets it when shelling to the CLI. Regular site exports (Studio UI, direct studio export CLI) do not apply the filter, preserving pre-existing backup behavior.
• meta.json filtering: Filter the plugin and theme lists in meta.json against the deploy-ignore filter. Without this, the server-side import would reinstall excluded plugins from WordPress.org even though their files were excluded from the archive
• Rename SYNC_EXCLUSIONS to SYNC_IGNORE_DEFAULTS — a superset of DEPLOY_IGNORE_DEFAULTS plus Studio-internal items (database, db.php, debug.log, sqlite-database-integration, cache).
• Remove redundant .replace(/\\/g, '/') path normalization in fs-utils.ts — the ignore library handles Windows backslash conversion internally
• Add ignore as a direct dependency in apps/cli and apps/studio (previously relied on transitive resolution)

Testing Instructions

Tip

It is probably easier to ask your AI assistant to perform the steps 2 and 3 for you, so you don't have to create the testing files manually.

1. Create a local site in Studio
2. Add a .deployignore file at the site root (e.g., ~/Studio/my-site/.deployignore) with the following content:

   # Ignore vendor dependencies in my-plugin, except important-lib
   wp-content/plugins/my-plugin/vendor/*
   !wp-content/plugins/my-plugin/vendor/important-lib
   
   # Ignore all log files
   *.log
   
   # Ignore old uploads
   wp-content/uploads/2024
   
   # Ignore a specific plugin
   wp-content/plugins/wordpress-seo
   

3. Create matching test files/folders in the site's wp-content:

   # Plugin with build artifacts
   mkdir -p wp-content/plugins/my-plugin/vendor/some-lib
   mkdir -p wp-content/plugins/my-plugin/vendor/important-lib
   echo '<?php // plugin entry' > wp-content/plugins/my-plugin/my-plugin.php
   echo '<?php // vendor file' > wp-content/plugins/my-plugin/vendor/some-lib/autoload.php
   echo '<?php // important' > wp-content/plugins/my-plugin/vendor/important-lib/loader.php
   echo 'build log' > wp-content/plugins/my-plugin/build.log
   
   # .git and node_modules inside the plugin (built-in defaults)
   mkdir -p wp-content/plugins/my-plugin/.git
   echo 'ref: refs/heads/main' > wp-content/plugins/my-plugin/.git/HEAD
   mkdir -p wp-content/plugins/my-plugin/node_modules/some-package
   echo '{"name":"some-package"}' > wp-content/plugins/my-plugin/node_modules/some-package/package.json
   
   # Old and new uploads
   mkdir -p wp-content/uploads/2024
   echo 'old photo' > wp-content/uploads/2024/photo.jpg
   mkdir -p wp-content/uploads/2025
   echo 'new photo' > wp-content/uploads/2025/photo.jpg
   

4. Install the wordpress-seo plugin on the site
5. Connect the local site to a target remote site (WordPress.com or Pressable)
6. Consider checking the target site to confirm it does not yet include any directories/files we want to ignore during the sync.
7. Open the Sync dialog and verify:
   • wordpress-seo plugin is hidden from the tree
   • akismet and my-plugin are still visible
   • uploads/2024 directory is hidden
   • uploads/2025 is still visible
8. Push to WordPress.com / Pressable and verify (e.g through a SSH connection to the WoA site):
   • vendor/some-lib/ is excluded from the push
   • vendor/important-lib/ is included (negation pattern)
   • *.log files are excluded
   • uploads/2024/ is excluded, uploads/2025/ is present
   • wordpress-seo plugin is excluded and not reinstalled by the server
9. Test the CLI push with the same .deployignore file:

   npm run cli:build && node apps/cli/dist/cli/main.mjs push --path {path-to-your-studio-site}
   

10. Verify the same exclusions apply as in step 7 & step 8 (check the target site again after the CLI push).
11. Verify that .git and node_modules inside my-plugin are excluded by built-in defaults
12. Verify that site export (backup) is unaffected by .deployignore — the filter is only applied during sync push, not when using Studio UI "Export site" or running studio export directly

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[ivan-ottinger]

These changes are required because otherwise the .deployignored plugins/themes would be reinstalled on the target site.

[Copilot]

Pull request overview

Extends existing .deployignore support to Studio’s Site Sync flow (sync tree UI + push/export), ensuring ignored files are consistently hidden/excluded and that meta.json doesn’t re-trigger server-side reinstalls of excluded plugins/themes.

Changes:

• Adds additionalDefaults support to the shared deploy-ignore filter and updates sync defaults to use it.
• Updates Sync tree listing/exclusion logic to rely on the deploy-ignore filter (while keeping dotfile hiding UI-only).
• Passes deploy-ignore filtering through the export pipeline and filters meta.json plugin/theme lists accordingly; downgrades ignore to v5 to avoid type conflicts.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/common/package.json	Downgrades ignore dependency to ^5.3.2.
tools/common/lib/deploy-ignore.ts	Adds additionalDefaults parameter to createDeployIgnoreFilter.
package-lock.json	Updates lockfile entries to reflect ignore@5.3.2 usage.
apps/studio/src/modules/sync/lib/tree-utils.ts	Reworks sync exclusion logic to use a deploy-ignore filter + dotfile hiding.
apps/studio/src/modules/sync/lib/ipc-handlers.ts	Creates deploy-ignore filter during push export and passes it into ExportOptions.
apps/studio/src/modules/sync/constants.ts	Renames/adjusts sync exclusion defaults to Studio-internal items only.
apps/studio/src/lib/import-export/export/types.ts	Adds optional deployIgnore?: Ignore to ExportOptions.
apps/studio/src/lib/import-export/export/exporters/default-exporter.ts	Applies deploy-ignore filtering during wp-content archive creation and filters meta.json plugins/themes.
apps/studio/src/ipc-handlers.ts	Updates listLocalFileTree to build/reuse deploy-ignore filter when listing sync tree.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fredrikekelund]

Noting that #3010 changed a lot of the sync logic on trunk. The CLI now also supports sync, and a lot of the internals moved to tools/common. We should update this PR accordingly

[fredrikekelund]

As I mentioned in #2955 (comment), a lot of the sync internals were moved around when we added sync support to the CLI. We should update this PR to reflect that.

Also, we currently have two copies of the exporter implementation: one for the CLI and another for the app. We should make sure this PR updates both places.

Lastly, I left some more detailed comments on the implementation.

[wpmobilebot]

📊 Performance Test Results

Comparing e01525a vs trunk

app-size

Metric	trunk	e01525a	Diff	Change
App Size (Mac)	1482.75 MB	1482.71 MB	0.04 MB	⚪ 0.0%

site-editor

Metric	trunk	e01525a	Diff	Change
load	1806 ms	1850 ms	+44 ms	⚪ 0.0%

site-startup

Metric	trunk	e01525a	Diff	Change
siteCreation	8086 ms	8079 ms	7 ms	⚪ 0.0%
siteStartup	4958 ms	4956 ms	2 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[ivan-ottinger]

I will continue with updates and testing tomorrow with fresh brain.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

tools/common/lib/fs-utils.ts:39

• path.relative() returns OS-specific separators (e.g., \ on Windows). Passing ignorePath with backslashes into ig.ignores() can cause .deployignore patterns that use / (like wp-content/plugins/**) to stop matching on Windows, and it can also break the built-in defaults when scanning nested paths. Normalize fileRelativeToRoot/ignorePath to POSIX (replace \\ with /) before calling ignores() (and keep pathPrefix joins consistent).

						const fileRelativeToRoot = path.relative( directoryPath, filePath );
						const ignorePath = pathPrefix
							? `${ pathPrefix }/${ fileRelativeToRoot }`
							: fileRelativeToRoot;
						try {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ivan-ottinger]

Alright, I have addressed the feedback and tested the changes on both macOS and Windows (pushing through the UI and the Studio CLI. Everything is running well, the files are getting excluded as described in the .deployignore.

From what I see this is the main remaining change to agree on. We can wait for the response from Antonio and/or Kat.

Apart from that, the PR will be ready for another review/test round.

[ivan-ottinger]

Hey @fredrikekelund 👋🏼🙂 I think we should be good merging this one. Feel free to let me know what you think.

[fredrikekelund]

Taking another look at this now

[fredrikekelund]

LGTM 👍 I left a couple of comments that'd be nice to address before landing this, not least the ignore dependency management.

Also interested to hear what you think about reading .gitignore, too, but that can easily be a follow-up.

[fredrikekelund]

Sorry for not thinking of this sooner, but I feel like it'd make sense to look for a .gitignore file here, too. Thoughts, @ivan-ottinger? I guess this could also be a follow-up PR.

[ivan-ottinger]

No worried. Do you mean to merge records from both files and use that to decide what should get synced to WordPress.com / Pressable? 🤔 Wouldn't it be mixing two different concepts?

[fredrikekelund]

Do you mean to merge records from both files and use that to decide what should get synced to WordPress.com / Pressable?

Yep, exactly. npm is an interesting example to look at. It uses an .npmignore file by default to determine what to include when publishing a package, and falls back to .gitignore (docs).

Wouldn't it be mixing two different concepts?

.gitignore might not be comprehensive in terms of what you want and don't want to sync to your remote site, but it's still a good indicator – especially if there's no .deployignore file.

.gitignore is specifically mentioned in #137, too.

[ivan-ottinger]

Sounds good. 👍🏼 I have created a follow-up task: STU-1633.

.gitignore is specifically mentioned in #137, too.

Yes, I am aware of that. Just when we discussed the scope in STU-16, we shifted to .deployignore at the end.

[fredrikekelund]

What we should really do, instead of asserting the array entry types, is use zod to parse the JSON returned by WP-CLI in getSitePlugins and getSiteThemes.

[ivan-ottinger]

I first tried to put it directly into this PR, but then decided to leave it for a new follow-up task: STU-1630 task - so we can unblock this PR.

[ivan-ottinger]

Hey @fredrikekelund 👋🏼 I have applied the latest changes that also required adjustment related to recent #3129 PR. Now we have a new --apply-deploy-ignore flag for the studio export to ensure we don't filter out files when the user is doing just a regular site export.

I have tested everything on macOS and Windows and haven't observed any regressions.