Add `strip_components` to `extract`/`download_and_extract` `http_arch… by willstranton · Pull Request #29281 · bazelbuild/bazel

willstranton · 2026-04-13T21:37:27Z

Add strip_components to extract/download_and_extract http_archive

Description

The strip_components attribute functions similar to tar --strip-components:

Strip NUMBER leading components from file names on extraction.

This is an alternative to the existing strip_prefix attribute, which required knowing the exact prefix to be stripped. Only one of the two attributes (strip_prefix, strip_components) can be set at one time.

Motivation

See #28879

Build API Changes

Has this been discussed in a design doc or issue? (Please link it)

See #28879

Is the change backward compatible?

Yes

If it's a breaking change, what is the migration plan?

N/A - this is not a breaking change.

Checklist

I have added tests for the new use cases (if any).
I have updated the documentation (if applicable).

Release Notes

RELNOTES[NEW]: Adds the strip_components attribute to extract/download_and_extract/http_archive to allow stripping of path components when extracting files.

meteorcloudy · 2026-04-15T14:26:49Z

which required knowing the exact prefix to be stripped.

If the source archive URL is deterministic, the exact prefix should be known?

willstranton · 2026-04-15T17:46:40Z

If the source archive URL is deterministic, the exact prefix should be known?

Yes, that's true, but it's inconvenient to have to examine an archive to determine that exact prefix. This pull request is a "quality of life" improvement. As you point out, it's not a "must have".

Summarizing from the community:

Copying the inconvenience expressed by the original issue filer in http_archive (also repository_ctx.extract) strip_components #28879 and why it's useful to have:

Archives often have a containing directories.

Sometimes, this is long or not easily memorable -- a version number, or a commit hash
Sometimes, this is not readily known. E.g. npm packages usually use a package/ prefix, but not always.
Usually, users don't actually care what the leading component is, they just want to remove it.
...
This feature is in both BSD and GNU tar; it's very useful.
While no mentioned in my original comment, it would also be very useful for archive_override (bzlmod).

I remember having to update dependencies manually before BCR. You had to update the tar archive AND the prefix that was stripped.

Feature request: download_and_extract(strip_prefix="*") #13960 is an earlier request from 2021 that expresses similar friction.

When first adding a http_archive (or alternative) to your workspace, it's easy enough to find what the top level directory is called... but with many archives it requires a bit more effort...
...with dependencies that change... this can get very tiresome....
My particular use case is a custom build definition that provides a simpler interface to private repositories... I don't know of any justification for requiring strip_prefix to be specified manually.

Issue 28879 has at least 2 members commenting on/in agreement with this proposal. With me being the author of this pull request, that makes 3. The second issue 13960 has two members commenting as well. So 5? people who want this solved somehow? I'll admit that counting users can be disingenuous since they could all be from the same company/friends rallying each other on. I have no relation to any of folks mentioned.

meteorcloudy · 2026-04-16T09:38:06Z

OK, thanks for the context! If we do this, we should also backport this to Bazel 8 & 9, so that modules can keep the compatibility with multiple LTS releases when using this feature.

Copilot

Pull request overview

Adds a new strip_components integer attribute/parameter (similar to tar --strip-components) to http_archive, repository_ctx.download_and_extract, and repository_ctx.extract, enabling prefix stripping without knowing an exact directory name.

Changes:

Introduces strip_components plumbing from Starlark (http_archive, download_and_extract, extract) down to the Java decompressor layer.
Implements component stripping during extraction for .zip, .7z, and tar-based archives.
Adds/updates integration + unit tests covering component stripping and rename-ordering behavior.

Reviewed changes

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

Show a summary per file

File	Description
tools/build_defs/repo/http.bzl	Adds `strip_components` attr, enforces mutual exclusivity with `strip_prefix`, passes through to `download_and_extract`.
src/main/java/com/google/devtools/build/lib/vfs/PathFragment.java	Adds `PathFragment.stripComponents(int)` utility used by decompressors.
src/main/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContext.java	Adds `strip_components` params to `download_and_extract`/`extract` and wires into decompression.
src/main/java/com/google/devtools/build/lib/bazel/repository/decompressor/DecompressorDescriptor.java	Adds `stripComponents` field + builder validation for mutual exclusivity with `prefix`.
src/main/java/com/google/devtools/build/lib/bazel/repository/decompressor/ZipDecompressor.java	Applies component stripping to zip entry paths before extraction.
src/main/java/com/google/devtools/build/lib/bazel/repository/decompressor/SevenZDecompressor.java	Applies component stripping to 7z entry paths before extraction.
src/main/java/com/google/devtools/build/lib/bazel/repository/decompressor/CompressedTarFunction.java	Applies component stripping to tar entry paths before extraction.
src/main/java/com/google/devtools/build/lib/bazel/repository/decompressor/CompressedFunction.java	Updates docs to note `stripComponents` is ignored for single-file compressor formats.
src/test/shell/bazel/external_integration_test.sh	Adds `http_archive` integration coverage for `strip_components` (tar/zip + add_prefix).
src/test/java/com/google/devtools/build/lib/vfs/PathFragmentTest.java	Adds unit tests for `PathFragment.stripComponents`.
src/test/java/com/google/devtools/build/lib/bazel/repository/starlark/StarlarkBaseExternalContextTest.java	Updates test calls for new `downloadAndExtract` signature.
src/test/java/com/google/devtools/build/lib/bazel/repository/decompressor/ZipDecompressorTest.java	Adds zip decompression tests for `strip_components` (+ rename ordering).
src/test/java/com/google/devtools/build/lib/bazel/repository/decompressor/SevenZDecompressorTest.java	Adds 7z decompression tests for `strip_components` (+ rename ordering + strip-all).
src/test/java/com/google/devtools/build/lib/bazel/repository/decompressor/CompressedTarFunctionTest.java	Adds tar.gz decompression tests for `strip_components` (+ rename ordering).
src/test/tools/bzlmod/MODULE.bazel.lock	Updates lockfile digests due to test/module changes.

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

meteorcloudy · 2026-04-16T13:37:07Z

Thanks, please run Please run "bazel run //src/test/tools/bzlmod:update_default_lock_file" to address CI failure

meteorcloudy · 2026-04-16T13:40:46Z

Let me know this is fixed, I will add the import label

…ive` The `strip_components` attribute functions similar to tar --strip-components: > Strip NUMBER leading components from file names on extraction. This is an alternative to the existing `strip_prefix` attribute, which required knowing the exact prefix to be stripped. Only one of the two attributes (`strip_prefix`, `strip_components`) can be set at one time. Fixes bazelbuild#28879 RELNOTES[NEW]: Adds the `strip_components` attribute to `extract`/`download_and_extract`/`http_archive` to allow stripping of path components when extracting files.

willstranton · 2026-04-16T19:49:43Z

Let me know this is fixed, I will add the import label

CI now passing.

meteorcloudy · 2026-04-17T13:45:07Z

@bazel-io fork 8.7.0

meteorcloudy · 2026-04-17T13:45:13Z

@bazel-io fork 9.1.0

This PR updates the documentation for `http_archive` to include the new `strip_components` attribute and clarifies the mutual exclusivity between `strip_prefix` and `strip_components`. Fixes bazelbuild#29281

This PR updates the documentation for the `http_archive` rule to include the newly added `strip_components` attribute. This attribute allows users to strip a specified number of leading path components from extracted files, offering an alternative to `strip_prefix`. Additionally, the documentation for `strip_prefix` has been updated to clarify that only one of `strip_prefix` or `strip_components` can be used. Original PR: bazelbuild#29281

This PR documents the new `strip_components` attribute for `http_archive` and the `strip_components` parameter for `ctx.download_and_extract` and `ctx.extract`. It also clarifies that `strip_prefix` and `strip_components` are mutually exclusive. This documentation is sourced from the code changes in bazelbuild#29281.

… .extract (placeholder) This PR introduces `strip_components` to `repository_ctx.download_and_extract` and `repository_ctx.extract` functions, allowing users to specify the number of leading path components to strip during extraction. This new attribute is mutually exclusive with `strip_prefix`. Original PR: bazelbuild#29281 **Note**: Due to persistent issues in programmatically identifying the correct documentation files within the Bazel repository (404 errors on multiple plausible paths, search API rate limits, and incomplete `list_docs_in_repo` results), the changes have been applied to placeholder files. A manual review is required to integrate this content into the definitive documentation for `repository_ctx` methods.

This PR introduces the `strip_components` attribute for `http_archive` and similar repository rules, allowing users to strip a specified number of leading path segments from extracted archives. It also clarifies that `strip_components` and `strip_prefix` are mutually exclusive. See original PR: bazelbuild#29281

This PR adds documentation for the new `strip_components` attribute for `repository_ctx.download_and_extract` and `repository_ctx.extract`, introduced in bazelbuild#29281. Since the original documentation file for `repository_ctx` could not be located, this PR creates new, minimal documentation files at the location suggested by broken links in the existing documentation.

…ion methods This PR updates the documentation for repository rules to reflect the addition of the `strip_components` attribute to `http_archive`, `repository_ctx.extract()`, and `repository_ctx.download_and_extract()`. The `http_archive` example now includes `strip_components`, and a note has been added to the `repository_ctx` section clarifying the use of `strip_components` and its mutual exclusivity with `strip_prefix` for extraction functions. This update corresponds to the changes in bazelbuild#29281.

This PR updates the documentation for `http_archive` to include the new `strip_components` attribute, as introduced in bazelbuild#29281. It also clarifies that `strip_components` and `strip_prefix` are mutually exclusive.

meteorcloudy · 2026-04-21T08:42:33Z

@willstranton Can you look into backporting this to 9.x and perhaps 8.x? The auto cherry-pick process failed #29323 (comment)

bazelbuild#29281) Add `strip_components` to `extract`/`download_and_extract` `http_archive` ### Description The `strip_components` attribute functions similar to `tar --strip-components`: > Strip NUMBER leading components from file names on extraction. This is an alternative to the existing `strip_prefix` attribute, which required knowing the exact prefix to be stripped. Only one of the two attributes (`strip_prefix`, `strip_components`) can be set at one time. ### Motivation See bazelbuild#28879 ### Build API Changes > 1. Has this been discussed in a design doc or issue? (Please link it) See bazelbuild#28879 > 2. Is the change backward compatible? Yes > 3. If it's a breaking change, what is the migration plan? N/A - this is not a breaking change. ### Checklist - [X] I have added tests for the new use cases (if any). - [X] I have updated the documentation (if applicable). ### Release Notes RELNOTES[NEW]: Adds the `strip_components` attribute to `extract`/`download_and_extract`/`http_archive` to allow stripping of path components when extracting files. Closes bazelbuild#29281 PiperOrigin-RevId: 902961227 Change-Id: I3fda77ec42c3d052f6655e42c8b57ec27667c758

willstranton · 2026-04-22T03:29:00Z

8.7.0: #29367
9.2.0: #29369

…ttp_arch… (bazelbuild#29367) …… (bazelbuild#29281) Add `strip_components` to `extract`/`download_and_extract` `http_archive` ### Description The `strip_components` attribute functions similar to `tar --strip-components`: > Strip NUMBER leading components from file names on extraction. This is an alternative to the existing `strip_prefix` attribute, which required knowing the exact prefix to be stripped. Only one of the two attributes (`strip_prefix`, `strip_components`) can be set at one time. ### Motivation See bazelbuild#28879 ### Build API Changes > 1. Has this been discussed in a design doc or issue? (Please link it) See bazelbuild#28879 > 2. Is the change backward compatible? Yes > 3. If it's a breaking change, what is the migration plan? N/A - this is not a breaking change. ### Checklist - [X] I have added tests for the new use cases (if any). - [X] I have updated the documentation (if applicable). ### Release Notes RELNOTES[NEW]: Adds the `strip_components` attribute to `extract`/`download_and_extract`/`http_archive` to allow stripping of path components when extracting files. Closes bazelbuild#29281. PiperOrigin-RevId: 902961227 Change-Id: I3fda77ec42c3d052f6655e42c8b57ec27667c758

…ttp_arch… (bazelbuild#29369) …… (bazelbuild#29281) Add `strip_components` to `extract`/`download_and_extract` `http_archive` ### Description The `strip_components` attribute functions similar to `tar --strip-components`: > Strip NUMBER leading components from file names on extraction. This is an alternative to the existing `strip_prefix` attribute, which required knowing the exact prefix to be stripped. Only one of the two attributes (`strip_prefix`, `strip_components`) can be set at one time. ### Motivation See bazelbuild#28879 ### Build API Changes > 1. Has this been discussed in a design doc or issue? (Please link it) See bazelbuild#28879 > 2. Is the change backward compatible? Yes > 3. If it's a breaking change, what is the migration plan? N/A - this is not a breaking change. ### Checklist - [X] I have added tests for the new use cases (if any). - [X] I have updated the documentation (if applicable). ### Release Notes RELNOTES[NEW]: Adds the `strip_components` attribute to `extract`/`download_and_extract`/`http_archive` to allow stripping of path components when extracting files. Closes bazelbuild#29281. PiperOrigin-RevId: 902961227 Change-Id: I3fda77ec42c3d052f6655e42c8b57ec27667c758

willstranton force-pushed the strip branch 2 times, most recently from da36a7a to 613bd88 Compare April 13, 2026 22:11

willstranton mentioned this pull request Apr 13, 2026

http_archive (also repository_ctx.extract) strip_components #28879

Closed

willstranton marked this pull request as ready for review April 13, 2026 22:12

github-actions Bot added team-ExternalDeps External dependency handling, remote repositiories, WORKSPACE file. team-Core Skyframe, bazel query, BEP, options parsing, bazelrc awaiting-review PR is awaiting review from an assigned reviewer labels Apr 13, 2026

bazel-docs-pull-requestor Bot mentioned this pull request Apr 13, 2026

docs preview: bazelbuild/bazel#29281 bazel-contrib/bazel-docs#356

Closed

meteorcloudy reviewed Apr 16, 2026

View reviewed changes

Comment thread tools/build_defs/repo/http.bzl Outdated

meteorcloudy requested a review from Copilot April 16, 2026 09:38

Copilot started reviewing on behalf of meteorcloudy April 16, 2026 09:38 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

willstranton force-pushed the strip branch from 613bd88 to 596b423 Compare April 16, 2026 10:28

willstranton added a commit to willstranton/bazel that referenced this pull request Apr 16, 2026

Address code review comments on bazelbuild#29281

596b423

meteorcloudy approved these changes Apr 16, 2026

View reviewed changes

willstranton added 3 commits April 16, 2026 19:17

Address code review comments on bazelbuild#29281

6dc5bd5

update lock file

31e1507

willstranton force-pushed the strip branch from 596b423 to 31e1507 Compare April 16, 2026 19:22

meteorcloudy added awaiting-PR-merge PR has been approved by a reviewer and is ready to be merge internally and removed awaiting-review PR is awaiting review from an assigned reviewer labels Apr 17, 2026

meteorcloudy approved these changes Apr 17, 2026

View reviewed changes

This was referenced Apr 17, 2026

[8.7.0] Add strip_components to extract/download_and_extract `http_arch… #29322

Closed

[9.2.0] Add strip_components to extract/download_and_extract `http_arch… #29323

Closed

deepalak56 mentioned this pull request Apr 18, 2026

docs: Add strip_components to repository_ctx.download_and_extract and .extract (placeholder) #29329

Closed

deepalak56 mentioned this pull request Apr 18, 2026

docs: Add strip_components to http_archive #29330

Closed

deepalak56 mentioned this pull request Apr 18, 2026

Docs: Add documentation for strip_components in repository_ctx #29333

Closed

deepalak56 mentioned this pull request Apr 18, 2026

Docs: Add strip_components to http_archive and repository_ctx extraction methods #29337

Closed

deepalak56 mentioned this pull request Apr 19, 2026

Docs: Add strip_components to http_archive documentation #29339

Closed

meteorcloudy mentioned this pull request Apr 20, 2026

Docs: Add strip_components and update strip_prefix for http_archive and related functions #29338

Closed

copybara-service Bot closed this in fba5888 Apr 21, 2026

github-actions Bot removed the awaiting-PR-merge PR has been approved by a reviewer and is ready to be merge internally label Apr 21, 2026

This was referenced Apr 22, 2026

[8.7.0] Add strip_components to extract/download_and_extract `http_arch… #29367

Merged

[9.2.0] Add strip_components to extract/download_and_extract `http_arch… #29369

Merged

Conversation

willstranton commented Apr 13, 2026

Description

Motivation

Build API Changes

Checklist

Release Notes

Uh oh!

meteorcloudy commented Apr 15, 2026

Uh oh!

willstranton commented Apr 15, 2026

Uh oh!

meteorcloudy commented Apr 16, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

meteorcloudy commented Apr 16, 2026

Uh oh!

meteorcloudy commented Apr 16, 2026

Uh oh!

willstranton commented Apr 16, 2026

Uh oh!

meteorcloudy commented Apr 17, 2026

Uh oh!

meteorcloudy commented Apr 17, 2026

Uh oh!

meteorcloudy commented Apr 21, 2026

Uh oh!

willstranton commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants