Skip to content

Revert "docs(snapshots): Document removal and rename detection for selective uploads (#17904)" #17931

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NicoHinderling merged 1 commit into from
May 29, 2026
Merged

Revert "docs(snapshots): Document removal and rename detection for selective uploads (#17904)" #17931

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 3 additions & 40 deletions docs/cli/snapshots.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,40 +58,7 @@ If you only upload a subset of your snapshots per CI run — for example, becaus
sentry-cli build snapshots ./snapshots --app-id web-frontend --selective
```

When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as unchanged (skipped) rather than removed.

### Detecting Removals and Renames in Selective Mode

By default, `--selective` cannot detect removals or renames because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset. To enable removal and rename detection, pass the full list of image file names from your test suite using one of:

- `--all-image-file-names <NAMES>` — a comma-separated list of all image file names.
- `--all-image-file-names-file <PATH>` — a path to a file (`.txt`, `.csv`, etc.) containing all image file names, one per line.
- `--all-image-file-names-as-regex <PATTERNS>` — a comma-separated list of regex patterns matching all image file names.
- `--all-image-file-names-as-regex-file <PATH>` — a path to a file containing regex patterns, one per line.

<Alert level="warning">
These four flags are mutually exclusive — you can only use one per upload.
</Alert>

All four flags implicitly enable `--selective`.

```bash
# Literal names
sentry-cli build snapshots ./snapshots \
--app-id web-frontend \
--all-image-file-names "homepage.png,settings/profile.png,settings/billing.png"

# Regex patterns
sentry-cli build snapshots ./snapshots \
--app-id web-frontend \
--all-image-file-names-as-regex ".*\.png"
```

With the image names or patterns provided, Sentry can tell apart three categories of missing images:

- **Skipped** — matched by the list/pattern but not uploaded (part of the test suite, just not run in this CI job).
- **Removed** — not matched and not uploaded (deliberately deleted from the test suite).
- **Renamed** — a new image has the same content hash as a missing one.
When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as unchanged rather than removed. Removals and renames cannot be detected when using `--selective`, because Sentry cannot distinguish a deliberately deleted snapshot from one that was not part of the subset.

## Diff Threshold

Expand All @@ -116,12 +83,8 @@ sentry-cli build snapshots [OPTIONS] --app-id <APP_ID> <PATH>
| `--auth-token <TOKEN>` | Sentry auth token. Can also be set via `SENTRY_AUTH_TOKEN`. |
| `-o`, `--org <ORG>` | Sentry organization slug. Can also be set via `SENTRY_ORG`. |
| `-p`, `--project <PROJECT>` | Sentry project slug. Can also be set via `SENTRY_PROJECT`. |
| `--selective` | Mark the upload as a subset. Use when uploading only a portion of your snapshots (for example, affected tests only). |
| `--all-image-file-names <NAMES>` | Comma-separated list of all image file names in the full test suite. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
| `--all-image-file-names-file <PATH>` | Path to a file (`.txt`, `.csv`, etc.) containing all image file names, one per line. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
| `--all-image-file-names-as-regex <PATTERNS>` | Comma-separated list of regex patterns matching all image file names in the full test suite. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
| `--all-image-file-names-as-regex-file <PATH>` | Path to a file containing regex patterns matching all image file names, one per line. Enables removal and rename detection in selective mode. Implicitly enables `--selective`. Mutually exclusive with the other `--all-image-*` flags. |
| `--diff-threshold <THRESHOLD>` | Float between `0.0` and `1.0`. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. |
| `--selective` | Mark the upload as a subset. Use when uploading only a portion of your snapshots (for example, affected tests only). |
| `--diff-threshold <THRESHOLD>` | Float between `0.0` and `1.0`. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. |
| `--head-sha <SHA>` | Commit SHA for the upload. Auto-detected in CI. |
| `--base-sha <SHA>` | Base commit SHA for comparison (PR only). Auto-detected from merge-base. |
| `--vcs-provider <PROVIDER>` | VCS provider (for example, `github`). Auto-detected from the git remote. |
Expand Down
7 changes: 0 additions & 7 deletions docs/product/snapshots/local-testing/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,6 @@ sentry-cli snapshots download --snapshot-id 259299

Use `--output` to change the destination directory. See the [full download reference](/cli/snapshots/#download-baselines) for all available flags.

<Alert level="info">
For very large test suites (tens of thousands of images), you may hit download
size limits. In that case, an alternative would be to generate your baseline snapshots
locally instead of downloading them (via your base branch). If you're running into this
limit with a smaller number of images than expected, [reach out to support](https://sentry.io/contact/support/).
</Alert>

## Diffing Locally

Use `sentry-cli snapshots diff` to compare two directories of images. See the [full diff reference](/cli/snapshots/#local-diff) for all available flags.
Expand Down
51 changes: 3 additions & 48 deletions docs/product/snapshots/uploading-snapshots/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,55 +75,10 @@ sentry-cli build snapshots ./snapshots --app-id web-frontend --selective

When an upload is marked as selective, Sentry only diffs the snapshots you uploaded. Any snapshot that exists in the base build but was not included in the upload is treated as **unchanged** (skipped) rather than removed.

### Detecting Removals and Renames

By default, selective mode cannot detect removals or renames. If you want Sentry to distinguish deliberately deleted snapshots from ones that simply weren't run, pass the full list of image file names from your test suite.

You can provide literal file names:

```bash
sentry-cli build snapshots ./snapshots \
--app-id web-frontend \
--all-image-file-names "homepage.png,settings/profile.png,settings/billing.png"
```

Or, for large test suites, use a file (`.txt`, `.csv`, etc.) with one name per line:

```bash
sentry-cli build snapshots ./snapshots \
--app-id web-frontend \
--all-image-file-names-file ./all-snapshot-names.txt
```

Alternatively, you can use regex patterns to match image names:

```bash
sentry-cli build snapshots ./snapshots \
--app-id web-frontend \
--all-image-file-names-as-regex ".*\.png"
```

Or a file of regex patterns, one per line:

```bash
sentry-cli build snapshots ./snapshots \
--app-id web-frontend \
--all-image-file-names-as-regex-file ./snapshot-patterns.txt
```

<Alert level="warning">
These four flags are mutually exclusive — you can only use one per upload.
</Alert>

All four flags implicitly enable `--selective`. With the image names or patterns provided, Sentry categorizes missing images as:

- **Skipped** — matched by the list/pattern but not uploaded (part of the suite, just not run in this job).
- **Removed** — not matched and not uploaded (deleted from the suite).
- **Renamed** — a new image has the same content hash as a missing one.

<Alert level="info">
Without one of the `--all-image-file-names*` flags, selective uploads treat
all missing base images as skipped. Removals and renames cannot be detected.
Because Sentry cannot distinguish a deliberately deleted snapshot from one
that was not part of the subset, removals and renames cannot be detected when
using `--selective`.
</Alert>

For the full `sentry-cli build snapshots` flag reference, see [Snapshots (CLI)](/cli/snapshots/).
Loading