From 947235d0aa598832516a013ba2e63b605b4590af Mon Sep 17 00:00:00 2001 From: deepalak56 Date: Sat, 18 Apr 2026 09:25:45 +0530 Subject: [PATCH] docs: Add strip_components to repository_ctx.download_and_extract and .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: https://github.com/bazelbuild/bazel/pull/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. --- .../rules/placeholder_repository_ctx_docs.mdx | 32 +++++++++++++++++++ .../rules/placeholder_repository_ctx_docs.md | 32 +++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 docs/rules/placeholder_repository_ctx_docs.mdx create mode 100644 site/en/rules/placeholder_repository_ctx_docs.md diff --git a/docs/rules/placeholder_repository_ctx_docs.mdx b/docs/rules/placeholder_repository_ctx_docs.mdx new file mode 100644 index 00000000000000..f208265f0234a2 --- /dev/null +++ b/docs/rules/placeholder_repository_ctx_docs.mdx @@ -0,0 +1,32 @@ +# Repository Context Functions + +This document describes functions available on the `repository_ctx` object. + +## download_and_extract + +`repository_ctx.download_and_extract(url, output="", sha256="", type="", strip_prefix="", strip_components=0)` + +Downloads a file from the given URL, extracts it, and optionally applies a strip prefix or strips leading path components. + +| Parameter | Description | +| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `url` | A string, or a list of strings, representing the URLs of the archives. | +| `output` | Directory to extract to. | +| `sha256` | The SHA256 checksum of the archive. | +| `type` | The archive type. If not specified, the type is inferred from the file extension. | +| `strip_prefix` | Strips the given prefix from the extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. Only one of `strip_prefix` or `strip_components` can be used. | +| `strip_components` | `int`, default `0`. Strip the given number of leading components from file paths on extraction. For example, if an archive contains `foo/bar/baz.txt` and `strip_components = 1`, then `bar/baz.txt` will be extracted. Only one of `strip_components` or `strip_prefix` can be used. Must be non-negative. | + +## extract + +`repository_ctx.extract(archive, output="", strip_prefix="", strip_components=0, type="")` + +Extracts an archive. + +| Parameter | Description | +| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `archive` | The archive to extract. | +| `output` | Directory to extract to. ------------------------------------------------------------------------ | +| `strip_prefix` | Strips the given prefix from the extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. Only one of `strip_prefix` or `strip_components` can be used. | +| `strip_components` | `int`, default `0`. Strip the given number of leading components from file paths on extraction. For example, if an archive contains `foo/bar/baz.txt` and `strip_components = 1`, then `bar/baz.txt` will be extracted. Only one of `strip_components` or `strip_prefix` can be used. Must be non-negative. | +| `type` | The archive type. If not specified, the type is inferred from the file extension. | diff --git a/site/en/rules/placeholder_repository_ctx_docs.md b/site/en/rules/placeholder_repository_ctx_docs.md new file mode 100644 index 00000000000000..f208265f0234a2 --- /dev/null +++ b/site/en/rules/placeholder_repository_ctx_docs.md @@ -0,0 +1,32 @@ +# Repository Context Functions + +This document describes functions available on the `repository_ctx` object. + +## download_and_extract + +`repository_ctx.download_and_extract(url, output="", sha256="", type="", strip_prefix="", strip_components=0)` + +Downloads a file from the given URL, extracts it, and optionally applies a strip prefix or strips leading path components. + +| Parameter | Description | +| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `url` | A string, or a list of strings, representing the URLs of the archives. | +| `output` | Directory to extract to. | +| `sha256` | The SHA256 checksum of the archive. | +| `type` | The archive type. If not specified, the type is inferred from the file extension. | +| `strip_prefix` | Strips the given prefix from the extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. Only one of `strip_prefix` or `strip_components` can be used. | +| `strip_components` | `int`, default `0`. Strip the given number of leading components from file paths on extraction. For example, if an archive contains `foo/bar/baz.txt` and `strip_components = 1`, then `bar/baz.txt` will be extracted. Only one of `strip_components` or `strip_prefix` can be used. Must be non-negative. | + +## extract + +`repository_ctx.extract(archive, output="", strip_prefix="", strip_components=0, type="")` + +Extracts an archive. + +| Parameter | Description | +| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `archive` | The archive to extract. | +| `output` | Directory to extract to. ------------------------------------------------------------------------ | +| `strip_prefix` | Strips the given prefix from the extracted files. For compatibility, this parameter may also be used under the deprecated name `stripPrefix`. Only one of `strip_prefix` or `strip_components` can be used. | +| `strip_components` | `int`, default `0`. Strip the given number of leading components from file paths on extraction. For example, if an archive contains `foo/bar/baz.txt` and `strip_components = 1`, then `bar/baz.txt` will be extracted. Only one of `strip_components` or `strip_prefix` can be used. Must be non-negative. | +| `type` | The archive type. If not specified, the type is inferred from the file extension. |