Add backup exclude options and defaults by whoiskatrin · Pull Request #437 · cloudflare/sandbox-sdk

whoiskatrin · 2026-03-02T19:04:17Z

Summary

This PR changes backup exclusion behavior to follow .gitignore by default instead of maintaining a hardcoded default ignore list.

createBackup() now supports:

useGitignore?: boolean to control whether git ignore rules are applied

Default behavior:

when the backup directory is inside a git repository, ignored paths are excluded from the archive
when useGitignore: false, gitignored paths are included
when the directory is not inside a git repository, backup proceeds without git-based exclusions

Why

The previous approach maintained a built-in list of default excluded paths. Based on review feedback, this PR moves away from that model and aligns backup behavior with standard tooling that respects .gitignore by default.

API and behavior

Changes in this PR:

remove exclude
remove excludeDefaults
add useGitignore?: boolean with default true
resolve ignored paths in the container via git instead of hand-maintaining defaults in the SDK
exclude .git when gitignore-based exclusion is enabled
gracefully fall back to a full backup when git is unavailable or the directory is not in a git repository

Tests

Updated backup workflow E2E coverage for:

respecting .gitignore by default
opting out with useGitignore: false
non-git directory fallback
nested .gitignore behavior

Validation run locally:

npm run typecheck

Reviewer notes

This PR now addresses the feedback to stop maintaining a default ignore list and instead use gitignore-driven defaults.

changeset-bot · 2026-03-02T19:04:25Z

🦋 Changeset detected

Latest commit: 9bdedbc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudflare/sandbox	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-03-02T19:09:37Z

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/sandbox-sdk/@cloudflare/sandbox@437

commit: 9bdedbc

github-actions · 2026-03-02T19:09:38Z

🐳 Docker Images Published

Variant	Image
Default	`cloudflare/sandbox:0.0.0-pr-437-2aecdff`
Python	`cloudflare/sandbox:0.0.0-pr-437-2aecdff-python`
OpenCode	`cloudflare/sandbox:0.0.0-pr-437-2aecdff-opencode`
Musl	`cloudflare/sandbox:0.0.0-pr-437-2aecdff-musl`
Desktop	`cloudflare/sandbox:0.0.0-pr-437-2aecdff-desktop`

Usage:

FROM cloudflare/sandbox:0.0.0-pr-437-2aecdff

Version: 0.0.0-pr-437-2aecdff

📦 Standalone Binary

For arbitrary Dockerfiles:

COPY --from=cloudflare/sandbox:0.0.0-pr-437-2aecdff /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]

Download via GitHub CLI:

gh run download 22720770848 -n sandbox-binary

Extract from Docker:

docker run --rm cloudflare/sandbox:0.0.0-pr-437-2aecdff cat /container-server/sandbox > sandbox && chmod +x sandbox

github-actions

OpenCode Review

This PR adds a much-needed feature for backup exclusion patterns - the implementation looks solid overall. The approach is clean: new optional parameters flow through all three layers (SDK → DO → Container), with proper validation at each boundary.

Strengths:

Proper three-layer architecture flow (SDK validates, container executes)
Good default exclude patterns (node_modules, .git, dist, build, etc.)
Comprehensive E2E tests that verify actual behavior
Shell escaping for security (preventing injection)
Temporary exclude file cleanup
Clear changeset with user-focused description

A few technical considerations:

The duplicate validation between packages/sandbox/src/sandbox.ts:192-213 and packages/sandbox-container/src/handlers/backup-handler.ts:24-42 follows the pattern of defense-in-depth validation but could be consolidated into shared utilities since the logic is identical.

The control character regex /[\u0000-\u001f\u007f]/ is correctly implemented in both places - this covers C0 control chars plus DEL, which is appropriate for shell safety.

The E2E tests properly verify end-to-end behavior rather than just mocking - they create actual files, exclude patterns, and verify the restored state. This gives good confidence the feature works as intended.

Minor improvement opportunities:

Consider extracting the control character validation to @repo/shared since it's duplicated
The temporary exclude file cleanup could benefit from explicit error handling (currently just logs warnings)

Documentation consideration:
The feature is well-documented in the type definitions, but the Cloudflare docs should be updated to include the new exclude and excludeDefaults parameters in the backup API documentation.

Overall this is a clean, well-tested implementation that follows the project's patterns. Ready to merge.

ghostwriternr

The only overarching issue I have with this PR is that ideally, this should behave similar to how most unix tools behave, which is gitignore, if present, is respected by default, but can be disabled with a flag. And there's an explicit flag for passing a list of paths to ignore. Us maintaining a list of "default" paths to ignore imo is definitely not a good path to pursue.

This adds end-to-end support for backup exclude patterns so users can skip dependency and build directories during createBackup. It also adds an excludeDefaults option for common paths and covers both exclude and default excludes with backup workflow E2E tests.

Use regex for control character detection in the SDK layer, matching the pattern already used for backup name validation. Add the same control character check to the container handler for defense-in-depth. Log warnings on exclude file cleanup failures instead of silently swallowing errors.

github-actions · 2026-03-07T12:57:38Z

🐳 Docker Images Published

Variant	Image
Default	`cloudflare/sandbox:0.0.0-pr-437-9bdedbc`
Python	`cloudflare/sandbox:0.0.0-pr-437-9bdedbc-python`
OpenCode	`cloudflare/sandbox:0.0.0-pr-437-9bdedbc-opencode`
Musl	`cloudflare/sandbox:0.0.0-pr-437-9bdedbc-musl`
Desktop	`cloudflare/sandbox:0.0.0-pr-437-9bdedbc-desktop`

Usage:

FROM cloudflare/sandbox:0.0.0-pr-437-9bdedbc

Version: 0.0.0-pr-437-9bdedbc

📦 Standalone Binary

For arbitrary Dockerfiles:

COPY --from=cloudflare/sandbox:0.0.0-pr-437-9bdedbc /container-server/sandbox /sandbox
ENTRYPOINT ["/sandbox"]

Download via GitHub CLI:

gh run download 22848212875 -n sandbox-binary

Extract from Docker:

docker run --rm cloudflare/sandbox:0.0.0-pr-437-9bdedbc cat /container-server/sandbox > sandbox && chmod +x sandbox

whoiskatrin · 2026-03-07T14:19:39Z

/bonk check why the tests are failing and fix it

mksquashfs -ef matches patterns containing '/' against the full absolute source path, not relative to the source directory root. The git ls-files output was relative, so no files were excluded.

Co-authored-by: whoiskatrin <whoiskatrin@users.noreply.github.com>

ask-bonk · 2026-03-07T14:26:27Z

Summary

Two E2E backup tests were failing:

"should respect gitignore rules by default"
"should resolve nested gitignore rules from the backup directory context"

Root cause: mksquashfs -ef (exclude file) matches patterns containing / against the full absolute filesystem path, not paths relative to the source directory root. The resolveGitignoreExcludePatterns method was writing relative paths from git ls-files (e.g., node_modules/a.txt) into the exclude file, but mksquashfs needed absolute paths (e.g., /workspace/.../app/node_modules/a.txt) to match correctly.

Fix (packages/sandbox-container/src/services/backup-service.ts:319-337): Convert the relative paths returned by git ls-files to absolute paths by joining them with the normalized backup directory. The .git exclude entry is also converted to an absolute path for consistency.

github run

Emit both direct and sticky mksquashfs exclude patterns so .gitignore-derived paths are excluded regardless of how the source directory is rooted in the archive.

Switch from newline to null-byte delimiters when listing gitignored files to handle paths containing spaces, quotes, and non-ASCII characters. Remove .git from hardcoded excludes since git ls-files already omits it.

whoiskatrin · 2026-03-09T10:21:25Z

Closing to reopen as a cleaner PR with focused review

whoiskatrin mentioned this pull request Mar 2, 2026

Add backup exclude options and defaults #436

Closed

This comment was marked as outdated.

Sign in to view

whoiskatrin marked this pull request as ready for review March 2, 2026 19:15

whoiskatrin requested a review from ghostwriternr as a code owner March 2, 2026 19:15

whoiskatrin mentioned this pull request Mar 4, 2026

sandbox-sdk: backup api improvements to include / exclude files cloudflare/cloudflare-docs#28760

Closed

ask-bonk Bot mentioned this pull request Mar 4, 2026

Doc backup exclude options per SDK#437 cloudflare/cloudflare-docs#28761

Closed

This comment was marked as outdated.

Sign in to view

github-actions Bot reviewed Mar 5, 2026

View reviewed changes

ghostwriternr requested changes Mar 6, 2026

View reviewed changes

whoiskatrin requested review from aron-cf and scuffi as code owners March 7, 2026 12:41

whoiskatrin and others added 6 commits March 7, 2026 12:47

Deduplicate backup exclude patterns

f2accbb

Trigger CI

abc6315

Trigger CI

e89082f

refactor(backup): use gitignore defaults

a23c2da

cloudflare deleted a comment from ask-bonk Bot Mar 7, 2026

whoiskatrin force-pushed the ignore-files branch from 51f89b0 to a23c2da Compare March 7, 2026 12:48

whoiskatrin added 3 commits March 7, 2026 13:03

fix(backup): normalize prefix matching in gitignore resolution

8368137

fix(backup): list ignored files without collapsing dirs

6c9a1f9

fix(backup): scope gitignore excludes to backup dir

67e66ff

ask-bonk Bot and others added 2 commits March 7, 2026 14:26

fix(backup): use absolute paths in mksquashfs exclude file

a8f7166

mksquashfs -ef matches patterns containing '/' against the full absolute source path, not relative to the source directory root. The git ls-files output was relative, so no files were excluded.

Use absolute paths in mksquashfs excludes

17fe81a

Co-authored-by: whoiskatrin <whoiskatrin@users.noreply.github.com>

whoiskatrin added 3 commits March 7, 2026 15:59

fix(backup): use wildcard mode for gitignore excludes

0643ac5

fix(backup): restore relative exclude patterns

cccad8d

Fix backup exclude path matching

ae42c52

Emit both direct and sticky mksquashfs exclude patterns so .gitignore-derived paths are excluded regardless of how the source directory is rooted in the archive.

whoiskatrin force-pushed the ignore-files branch from f7fe2d9 to ae42c52 Compare March 9, 2026 09:41

fix(backup): use null-delimited git ls-files output

9bdedbc

Switch from newline to null-byte delimiters when listing gitignored files to handle paths containing spaces, quotes, and non-ASCII characters. Remove .git from hardcoded excludes since git ls-files already omits it.

ghostwriternr mentioned this pull request Mar 9, 2026

Fix Docker bake building from main instead of PR branch #473

Merged

whoiskatrin closed this Mar 9, 2026

Navigation Menu

Repository navigation

Add backup exclude options and defaults - #437

Add backup exclude options and defaults#437
whoiskatrin wants to merge 15 commits into
mainfrom
ignore-files

whoiskatrin commented Mar 2, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

pkg-pr-new Bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Mar 2, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions Bot left a comment

Uh oh!

ghostwriternr left a comment

Uh oh!

github-actions Bot commented Mar 7, 2026 •

edited

Loading

Uh oh!

whoiskatrin commented Mar 7, 2026

Uh oh!

ask-bonk Bot commented Mar 7, 2026

Uh oh!

whoiskatrin commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

whoiskatrin commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

API and behavior

Tests

Reviewer notes

Uh oh!

changeset-bot Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

This comment was marked as outdated.

Uh oh!

pkg-pr-new Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🐳 Docker Images Published

📦 Standalone Binary

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

OpenCode Review

Uh oh!

ghostwriternr left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🐳 Docker Images Published

📦 Standalone Binary

Uh oh!

whoiskatrin commented Mar 7, 2026

Uh oh!

ask-bonk Bot commented Mar 7, 2026

Summary

Uh oh!

whoiskatrin commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

whoiskatrin commented Mar 2, 2026 •

edited

Loading

changeset-bot Bot commented Mar 2, 2026 •

edited

Loading

pkg-pr-new Bot commented Mar 2, 2026 •

edited

Loading

github-actions Bot commented Mar 2, 2026 •

edited

Loading

github-actions Bot commented Mar 7, 2026 •

edited

Loading