From 4c83a533d74e268aee0d632313b01ac3cfe56641 Mon Sep 17 00:00:00 2001 From: Nico Hinderling Date: Fri, 29 May 2026 14:56:51 -0500 Subject: [PATCH] Revert "docs(snapshots): Document removal and rename detection for selective uploads (#17904)" This reverts commit 07e394bfe7ccfaeaaf6b56c524dffc20a80428a1. --- docs/cli/snapshots.mdx | 43 ++-------------- .../product/snapshots/local-testing/index.mdx | 7 --- .../snapshots/uploading-snapshots/index.mdx | 51 ++----------------- 3 files changed, 6 insertions(+), 95 deletions(-) diff --git a/docs/cli/snapshots.mdx b/docs/cli/snapshots.mdx index afe24652c1b581..fc60b4d99ba09b 100644 --- a/docs/cli/snapshots.mdx +++ b/docs/cli/snapshots.mdx @@ -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 ` — a comma-separated list of all image file names. -- `--all-image-file-names-file ` — a path to a file (`.txt`, `.csv`, etc.) containing all image file names, one per line. -- `--all-image-file-names-as-regex ` — a comma-separated list of regex patterns matching all image file names. -- `--all-image-file-names-as-regex-file ` — a path to a file containing regex patterns, one per line. - - - These four flags are mutually exclusive — you can only use one per upload. - - -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 @@ -116,12 +83,8 @@ sentry-cli build snapshots [OPTIONS] --app-id | `--auth-token ` | Sentry auth token. Can also be set via `SENTRY_AUTH_TOKEN`. | | `-o`, `--org ` | Sentry organization slug. Can also be set via `SENTRY_ORG`. | | `-p`, `--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 ` | 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 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 ` | 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 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 ` | 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 ` | Float between `0.0` and `1.0`. Sentry only reports images as changed if the percentage of changed pixels exceeds this value. | | `--head-sha ` | Commit SHA for the upload. Auto-detected in CI. | | `--base-sha ` | Base commit SHA for comparison (PR only). Auto-detected from merge-base. | | `--vcs-provider ` | VCS provider (for example, `github`). Auto-detected from the git remote. | diff --git a/docs/product/snapshots/local-testing/index.mdx b/docs/product/snapshots/local-testing/index.mdx index a30cc928fb5daf..1faeed2cac2f02 100644 --- a/docs/product/snapshots/local-testing/index.mdx +++ b/docs/product/snapshots/local-testing/index.mdx @@ -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. - - 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/). - - ## 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. diff --git a/docs/product/snapshots/uploading-snapshots/index.mdx b/docs/product/snapshots/uploading-snapshots/index.mdx index a38cd9771ebc03..339b79fdae2454 100644 --- a/docs/product/snapshots/uploading-snapshots/index.mdx +++ b/docs/product/snapshots/uploading-snapshots/index.mdx @@ -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 -``` - - These four flags are mutually exclusive — you can only use one per upload. - - -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. - - - 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`. For the full `sentry-cli build snapshots` flag reference, see [Snapshots (CLI)](/cli/snapshots/).