> ## Documentation Index
> Fetch the complete documentation index at: https://bazel.build/llms.txt
> Use this file to discover all available pages before exploring further.

# utils repository rules

The following functions can be loaded from
`@bazel_tools//tools/build_defs/repo:utils.bzl`.

Utils for manipulating external repositories, once fetched.

### Setup

These utilities are intended to be used by other repository rules. They
can be loaded as follows.

```python theme={null}
load(
    "@bazel_tools//tools/build_defs/repo:utils.bzl",
    "workspace_and_buildfile",
    "patch",
    "update_attrs",
)
```

## download\_remote\_files

```
load("@bazel//tools/build_defs/repo:utils.bzl", "download_remote_files")

download_remote_files(<a href="#download_remote_files-ctx">ctx</a>, <a href="#download_remote_files-auth">auth</a>)
```

Utility function for downloading remote files.

This rule is intended to be used in the implementation function of
a repository rule. It assumes the parameters `remote_file_urls` and
`remote_file_integrity` to be present in `ctx.attr`.

Existing files will be overwritten.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="download_remote_files-ctx">
      <td>`ctx`</td>

      <td>
        required.

        The repository context of the repository rule calling this utility
        function.
      </td>
    </tr>

    <tr id="download_remote_files-auth">
      <td>`auth`</td>

      <td>
        optional.
        default is `None`

        An optional dict specifying authentication information for some of the URLs.
      </td>
    </tr>
  </tbody>
</table>

### Returns

dict mapping file paths to a download info.

## get\_auth

```
load("@bazel//tools/build_defs/repo:utils.bzl", "get_auth")

get_auth(<a href="#get_auth-ctx">ctx</a>, <a href="#get_auth-urls">urls</a>)
```

Utility function to obtain the correct auth dict for a list of urls from .netrc file.

Support optional netrc and auth\_patterns attributes if available.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="get_auth-ctx">
      <td>`ctx`</td>

      <td>
        required.

        The repository context of the repository rule calling this utility
        function.
      </td>
    </tr>

    <tr id="get_auth-urls">
      <td>`urls`</td>

      <td>
        required.

        the list of urls to read
      </td>
    </tr>
  </tbody>
</table>

### Returns

the auth dict which can be passed to repository\_ctx.download

## maybe

```
load("@bazel//tools/build_defs/repo:utils.bzl", "maybe")

maybe(<a href="#maybe-repo_rule">repo_rule</a>, <a href="#maybe-name">name</a>, <a href="#maybe-kwargs">**kwargs</a>)
```

Utility function for only adding a repository if it's not already present.

This is to implement safe repositories.bzl macro documented in
[https://bazel.build/versions/8.9.0/rules/deploying#dependencies](https://bazel.build/versions/8.9.0/rules/deploying.md#dependencies).

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="maybe-repo_rule">
      <td>`repo_rule`</td>

      <td>
        required.

        repository rule function.
      </td>
    </tr>

    <tr id="maybe-name">
      <td>`name`</td>

      <td>
        required.

        name of the repository to create.
      </td>
    </tr>

    <tr id="maybe-kwargs">
      <td>`kwargs`</td>

      <td>
        optional.

        remaining arguments that are passed to the repo\_rule function.
      </td>
    </tr>
  </tbody>
</table>

### Returns

Nothing, defines the repository when needed as a side-effect.

## parse\_netrc

```
load("@bazel//tools/build_defs/repo:utils.bzl", "parse_netrc")

parse_netrc(<a href="#parse_netrc-contents">contents</a>, <a href="#parse_netrc-filename">filename</a>)
```

Utility function to parse at least a basic .netrc file.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="parse_netrc-contents">
      <td>`contents`</td>

      <td>
        required.

        input for the parser.
      </td>
    </tr>

    <tr id="parse_netrc-filename">
      <td>`filename`</td>

      <td>
        optional.
        default is `"a .netrc file"`

        filename to use in error messages, if any.
      </td>
    </tr>
  </tbody>
</table>

### Returns

dict mapping a machine names to a dict with the information provided
about them

## patch

```
load("@bazel//tools/build_defs/repo:utils.bzl", "patch")

patch(<a href="#patch-ctx">ctx</a>, <a href="#patch-patches">patches</a>, <a href="#patch-patch_cmds">patch_cmds</a>, <a href="#patch-patch_cmds_win">patch_cmds_win</a>, <a href="#patch-patch_tool">patch_tool</a>, <a href="#patch-patch_args">patch_args</a>, <a href="#patch-auth">auth</a>, <a href="#patch-patch_directory">patch_directory</a>)
```

Implementation of patching an already extracted repository.

This rule is intended to be used in the implementation function of
a repository rule. If the parameters `patches`, `patch_tool`,
`patch_args`, `patch_cmds`, `patch_cmds_win` and `patch_directory`
are not specified then they are taken from `ctx.attr`.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="patch-ctx">
      <td>`ctx`</td>

      <td>
        required.

        The repository context of the repository rule calling this utility
        function.
      </td>
    </tr>

    <tr id="patch-patches">
      <td>`patches`</td>

      <td>
        optional.
        default is `None`

        The patch files to apply. List of strings, Labels, or paths.
      </td>
    </tr>

    <tr id="patch-patch_cmds">
      <td>`patch_cmds`</td>

      <td>
        optional.
        default is `None`

        Bash commands to run for patching, passed one at a
        time to bash -c. List of strings
      </td>
    </tr>

    <tr id="patch-patch_cmds_win">
      <td>`patch_cmds_win`</td>

      <td>
        optional.
        default is `None`

        Powershell commands to run for patching, passed
        one at a time to powershell /c. List of strings. If the
        boolean value of this parameter is false, patch\_cmds will be
        used and this parameter will be ignored.
      </td>
    </tr>

    <tr id="patch-patch_tool">
      <td>`patch_tool`</td>

      <td>
        optional.
        default is `None`

        Path of the patch tool to execute for applying
        patches. String.
      </td>
    </tr>

    <tr id="patch-patch_args">
      <td>`patch_args`</td>

      <td>
        optional.
        default is `None`

        Arguments to pass to the patch tool. List of strings.
      </td>
    </tr>

    <tr id="patch-auth">
      <td>`auth`</td>

      <td>
        optional.
        default is `None`

        An optional dict specifying authentication information for some of the URLs.
      </td>
    </tr>

    <tr id="patch-patch_directory">
      <td>`patch_directory`</td>

      <td>
        optional.
        default is `None`

        Directory relative to the repository root in which to
        apply `patches` and run `patch_cmds`. Remote patches are always applied
        at the repository root. Defaults to the repository root.
      </td>
    </tr>
  </tbody>
</table>

### Returns

dict mapping remote patch URLs to a download info.

## read\_netrc

```
load("@bazel//tools/build_defs/repo:utils.bzl", "read_netrc")

read_netrc(<a href="#read_netrc-ctx">ctx</a>, <a href="#read_netrc-filename">filename</a>)
```

Utility function to parse at least a basic .netrc file.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="read_netrc-ctx">
      <td>`ctx`</td>

      <td>
        required.

        The repository context of the repository rule calling this utility
        function.
      </td>
    </tr>

    <tr id="read_netrc-filename">
      <td>`filename`</td>

      <td>
        required.

        the name of the .netrc file to read
      </td>
    </tr>
  </tbody>
</table>

### Returns

dict mapping a machine names to a dict with the information provided
about them

## read\_user\_netrc

```
load("@bazel//tools/build_defs/repo:utils.bzl", "read_user_netrc")

read_user_netrc(<a href="#read_user_netrc-ctx">ctx</a>)
```

Read user's default netrc file.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="read_user_netrc-ctx">
      <td>`ctx`</td>

      <td>
        required.

        The repository context of the repository rule calling this utility function.
      </td>
    </tr>
  </tbody>
</table>

### Returns

dict mapping a machine names to a dict with the information provided about them.

## symlink\_files

```
load("@bazel//tools/build_defs/repo:utils.bzl", "symlink_files")

symlink_files(<a href="#symlink_files-ctx">ctx</a>)
```

Utility function for symlinking local files.

This is intended to be used in the implementation function of a repository rule. It assumes the
parameter `files` is present in `ctx.attr`.

Existing files will be overwritten.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="symlink_files-ctx">
      <td>`ctx`</td>

      <td>
        required.

        The repository context of the repository rule calling this utility
        function.
      </td>
    </tr>
  </tbody>
</table>

## update\_attrs

```
load("@bazel//tools/build_defs/repo:utils.bzl", "update_attrs")

update_attrs(<a href="#update_attrs-orig">orig</a>, <a href="#update_attrs-keys">keys</a>, <a href="#update_attrs-override">override</a>)
```

Utility function for altering and adding the specified attributes to a particular repository rule invocation.

This is used to make a rule reproducible.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="update_attrs-orig">
      <td>`orig`</td>

      <td>
        required.

        dict of actually set attributes (either explicitly or implicitly)
        by a particular rule invocation
      </td>
    </tr>

    <tr id="update_attrs-keys">
      <td>`keys`</td>

      <td>
        required.

        complete set of attributes defined on this rule
      </td>
    </tr>

    <tr id="update_attrs-override">
      <td>`override`</td>

      <td>
        required.

        dict of attributes to override or add to orig
      </td>
    </tr>
  </tbody>
</table>

### Returns

dict of attributes with the keys from override inserted/updated

## use\_netrc

```
load("@bazel//tools/build_defs/repo:utils.bzl", "use_netrc")

use_netrc(<a href="#use_netrc-netrc">netrc</a>, <a href="#use_netrc-urls">urls</a>, <a href="#use_netrc-patterns">patterns</a>)
```

Compute an auth dict from a parsed netrc file and a list of URLs.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="use_netrc-netrc">
      <td>`netrc`</td>

      <td>
        required.

        a netrc file already parsed to a dict, e.g., as obtained from
        read\_netrc
      </td>
    </tr>

    <tr id="use_netrc-urls">
      <td>`urls`</td>

      <td>
        required.

        a list of URLs.
      </td>
    </tr>

    <tr id="use_netrc-patterns">
      <td>`patterns`</td>

      <td>
        required.

        optional dict of url to authorization patterns
      </td>
    </tr>
  </tbody>
</table>

### Returns

dict suitable as auth argument for ctx.download; more precisely, the dict
will map all URLs where the netrc file provides login and password to a
dict containing the corresponding login, password and optional authorization pattern,
as well as the mapping of "type" to "basic" or "pattern".

## workspace\_and\_buildfile

```
load("@bazel//tools/build_defs/repo:utils.bzl", "workspace_and_buildfile")

workspace_and_buildfile(<a href="#workspace_and_buildfile-ctx">ctx</a>)
```

Utility function for writing a BUILD file.

This rule is intended to be used in the implementation function of a
repository rule.
It assumes the parameters `name`, `build_file`, and `build_file_content` to
be present in `ctx.attr`; the latter two possibly with value None.

### Parameters

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="workspace_and_buildfile-ctx">
      <td>`ctx`</td>

      <td>
        required.

        The repository context of the repository rule calling this utility
        function.
      </td>
    </tr>
  </tbody>
</table>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.