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

# git repository rules

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

Rules for cloning external git repositories.

## git\_repository

```
load("@bazel//tools/build_defs/repo:git.bzl", "git_repository")

git_repository(<a href="#git_repository-name">name</a>, <a href="#git_repository-branch">branch</a>, <a href="#git_repository-build_file">build_file</a>, <a href="#git_repository-build_file_content">build_file_content</a>, <a href="#git_repository-canonical_id">canonical_id</a>, <a href="#git_repository-commit">commit</a>, <a href="#git_repository-init_submodules">init_submodules</a>,
               <a href="#git_repository-patch_args">patch_args</a>, <a href="#git_repository-patch_cmds">patch_cmds</a>, <a href="#git_repository-patch_cmds_win">patch_cmds_win</a>, <a href="#git_repository-patch_strip">patch_strip</a>, <a href="#git_repository-patch_tool">patch_tool</a>, <a href="#git_repository-patches">patches</a>,
               <a href="#git_repository-recursive_init_submodules">recursive_init_submodules</a>, <a href="#git_repository-remote">remote</a>, <a href="#git_repository-remote_module_file_integrity">remote_module_file_integrity</a>,
               <a href="#git_repository-remote_module_file_urls">remote_module_file_urls</a>, <a href="#git_repository-remote_patch_strip">remote_patch_strip</a>, <a href="#git_repository-remote_patches">remote_patches</a>, <a href="#git_repository-repo_mapping">repo_mapping</a>,
               <a href="#git_repository-shallow_since">shallow_since</a>, <a href="#git_repository-sparse_checkout_file">sparse_checkout_file</a>, <a href="#git_repository-sparse_checkout_patterns">sparse_checkout_patterns</a>, <a href="#git_repository-strip_prefix">strip_prefix</a>, <a href="#git_repository-tag">tag</a>,
               <a href="#git_repository-verbose">verbose</a>, <a href="#git_repository-workspace_file">workspace_file</a>, <a href="#git_repository-workspace_file_content">workspace_file_content</a>)
```

Clone an external git repository.

Clones a Git repository, checks out the specified branch, tag, or commit, and
makes its targets available for binding. If no branch, tag or commit is
specified, check out the repository's default branch. Also determine the id
and date of the commit that was checked out, and return a dict with
parameters that provide a reproducible version of this rule (which a tag or
branch not necessarily is).

Bazel will first try to perform a shallow fetch of only the specified commit.
If that fails (usually due to missing server support), it will fall back to a
full fetch of the repository.

Prefer [`http_archive`](https://bazel.build/versions/8.9.0/rules/lib/repo/http#http_archive) to `git_repository`.
The reasons are:

* Git repository rules depend on system `git(1)` whereas the HTTP downloader is built
  into Bazel and has no system dependencies.
* `http_archive` supports a list of `urls` as mirrors, and `git_repository` supports only
  a single `remote`.
* `http_archive` works with the [repository cache](https://bazel.build/versions/8.9.0/run/build.md#repository-cache), but not
  `git_repository`. See
  [#5116](https://github.com/bazelbuild/bazel/issues/5116) for more information.

**ATTRIBUTES**

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="git_repository-name">
      <td>`name`</td>

      <td>
        [Name](https://bazel.build/versions/8.9.0/concepts/labels.md#target-names); required

        A unique name for this repository.
      </td>
    </tr>

    <tr id="git_repository-branch">
      <td>`branch`</td>

      <td>
        String; optional

        branch in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified.
      </td>
    </tr>

    <tr id="git_repository-build_file">
      <td>`build_file`</td>

      <td>
        [Label](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        The file to use as the BUILD file for this repository.This attribute is an absolute label (use '@//' for the main repo). The file does not need to be named BUILD, but can be (something like BUILD.new-repo-name may work well for distinguishing it from the repository's actual BUILD files.
      </td>
    </tr>

    <tr id="git_repository-build_file_content">
      <td>`build_file_content`</td>

      <td>
        String; optional

        The content for the BUILD file for this repository.
      </td>
    </tr>

    <tr id="git_repository-canonical_id">
      <td>`canonical_id`</td>

      <td>
        String; optional

        A canonical ID of the file downloaded.

        If specified and non-empty, Bazel will not take the file from cache, unless it
        was added to the cache by a request with the same canonical ID.

        If unspecified or empty, Bazel by default uses the URLs of the file as the
        canonical ID. This helps catch the common mistake of updating the URLs without
        also updating the hash, resulting in builds that succeed locally but fail on
        machines without the file in the cache. This behavior can be disabled with
        \--repo\_env=BAZEL\_HTTP\_RULES\_URLS\_AS\_DEFAULT\_CANONICAL\_ID=0.
      </td>
    </tr>

    <tr id="git_repository-commit">
      <td>`commit`</td>

      <td>
        String; optional

        specific commit to be checked out. Precisely one of branch, tag, or commit must be specified.
      </td>
    </tr>

    <tr id="git_repository-init_submodules">
      <td>`init_submodules`</td>

      <td>
        Boolean; optional

        Whether to clone submodules in the repository.
      </td>
    </tr>

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

      <td>
        List of strings; optional

        The arguments given to the patch tool. Defaults to -p0 (see the `patch_strip` attribute), however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch\_tool attribute is not specified, `patch` will be used.
      </td>
    </tr>

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

      <td>
        List of strings; optional

        Sequence of Bash commands to be applied on Linux/Macos after patches are applied.
      </td>
    </tr>

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

      <td>
        List of strings; optional

        Sequence of Powershell commands to be applied on Windows after patches are applied. If this attribute is not set, patch\_cmds will be executed on Windows, which requires Bash binary to exist.
      </td>
    </tr>

    <tr id="git_repository-patch_strip">
      <td>`patch_strip`</td>

      <td>
        Integer; optional

        When set to `N`, this is equivalent to inserting `-pN` to the beginning of `patch_args`.
      </td>
    </tr>

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

      <td>
        String; optional

        The patch(1) utility to use. If this is specified, Bazel will use the specified patch tool instead of the Bazel-native patch implementation.
      </td>
    </tr>

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

      <td>
        [List of labels](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        A list of files that are to be applied as patches after extracting the archive. By default, it uses the Bazel-native patch implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use patch command line tool if `patch_tool` attribute is specified or there are arguments other than `-p` in `patch_args` attribute.
      </td>
    </tr>

    <tr id="git_repository-recursive_init_submodules">
      <td>`recursive_init_submodules`</td>

      <td>
        Boolean; optional

        Whether to clone submodules recursively in the repository.
      </td>
    </tr>

    <tr id="git_repository-remote">
      <td>`remote`</td>

      <td>
        String; required

        The URI of the remote Git repository
      </td>
    </tr>

    <tr id="git_repository-remote_module_file_integrity">
      <td>`remote_module_file_integrity`</td>

      <td>
        String; optional

        For internal use only.
      </td>
    </tr>

    <tr id="git_repository-remote_module_file_urls">
      <td>`remote_module_file_urls`</td>

      <td>
        List of strings; optional

        For internal use only.
      </td>
    </tr>

    <tr id="git_repository-remote_patch_strip">
      <td>`remote_patch_strip`</td>

      <td>
        Integer; optional

        The number of leading slashes to be stripped from the file name in the remote patches.
      </td>
    </tr>

    <tr id="git_repository-remote_patches">
      <td>`remote_patches`</td>

      <td>
        [Dictionary: String -> String](https://bazel.build/versions/8.9.0/rules/lib/dict); optional

        A map of patch file URL to its integrity value, they are applied after cloning the repository and before applying patch files from the `patches` attribute. It uses the Bazel-native patch implementation, you can specify the patch strip number with `remote_patch_strip`
      </td>
    </tr>

    <tr id="git_repository-repo_mapping">
      <td>`repo_mapping`</td>

      <td>
        [Dictionary: String -> String](https://bazel.build/versions/8.9.0/rules/lib/dict); optional

        In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

        For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

        This attribute is *not* supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).
      </td>
    </tr>

    <tr id="git_repository-shallow_since">
      <td>`shallow_since`</td>

      <td>
        String; optional

        an optional date, not after the specified commit; the argument is not allowed if a tag or branch is specified (which can always be cloned with --depth=1). Setting such a date close to the specified commit may allow for a shallow clone of the repository even if the server does not support shallow fetches of arbitrary commits. Due to bugs in git's --shallow-since implementation, using this attribute is not recommended as it may result in fetch failures.
      </td>
    </tr>

    <tr id="git_repository-sparse_checkout_file">
      <td>`sparse_checkout_file`</td>

      <td>
        [Label](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        File containing .gitignore-style patterns for a sparse checkout of files in this repository. Either `sparse_checkout_patterns` or `sparse_checkout_file` may be specified, or neither, but not both.
      </td>
    </tr>

    <tr id="git_repository-sparse_checkout_patterns">
      <td>`sparse_checkout_patterns`</td>

      <td>
        List of strings; optional

        Sequence of patterns for a sparse checkout of files in this repository.
      </td>
    </tr>

    <tr id="git_repository-strip_prefix">
      <td>`strip_prefix`</td>

      <td>
        String; optional

        A directory prefix to strip from the extracted files.
      </td>
    </tr>

    <tr id="git_repository-tag">
      <td>`tag`</td>

      <td>
        String; optional

        tag in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified.
      </td>
    </tr>

    <tr id="git_repository-verbose">
      <td>`verbose`</td>

      <td>
        Boolean; optional
      </td>
    </tr>

    <tr id="git_repository-workspace_file">
      <td>`workspace_file`</td>

      <td>
        [Label](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        No-op attribute; do not use.
      </td>
    </tr>

    <tr id="git_repository-workspace_file_content">
      <td>`workspace_file_content`</td>

      <td>
        String; optional

        No-op attribute; do not use.
      </td>
    </tr>
  </tbody>
</table>

**ENVIRONMENT VARIABLES**

This repository rule depends on the following environment variables:

* `BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID`

## new\_git\_repository

```
load("@bazel//tools/build_defs/repo:git.bzl", "new_git_repository")

new_git_repository(<a href="#new_git_repository-name">name</a>, <a href="#new_git_repository-branch">branch</a>, <a href="#new_git_repository-build_file">build_file</a>, <a href="#new_git_repository-build_file_content">build_file_content</a>, <a href="#new_git_repository-canonical_id">canonical_id</a>, <a href="#new_git_repository-commit">commit</a>,
                   <a href="#new_git_repository-init_submodules">init_submodules</a>, <a href="#new_git_repository-patch_args">patch_args</a>, <a href="#new_git_repository-patch_cmds">patch_cmds</a>, <a href="#new_git_repository-patch_cmds_win">patch_cmds_win</a>, <a href="#new_git_repository-patch_strip">patch_strip</a>, <a href="#new_git_repository-patch_tool">patch_tool</a>,
                   <a href="#new_git_repository-patches">patches</a>, <a href="#new_git_repository-recursive_init_submodules">recursive_init_submodules</a>, <a href="#new_git_repository-remote">remote</a>, <a href="#new_git_repository-remote_module_file_integrity">remote_module_file_integrity</a>,
                   <a href="#new_git_repository-remote_module_file_urls">remote_module_file_urls</a>, <a href="#new_git_repository-remote_patch_strip">remote_patch_strip</a>, <a href="#new_git_repository-remote_patches">remote_patches</a>, <a href="#new_git_repository-repo_mapping">repo_mapping</a>,
                   <a href="#new_git_repository-shallow_since">shallow_since</a>, <a href="#new_git_repository-sparse_checkout_file">sparse_checkout_file</a>, <a href="#new_git_repository-sparse_checkout_patterns">sparse_checkout_patterns</a>, <a href="#new_git_repository-strip_prefix">strip_prefix</a>, <a href="#new_git_repository-tag">tag</a>,
                   <a href="#new_git_repository-verbose">verbose</a>, <a href="#new_git_repository-workspace_file">workspace_file</a>, <a href="#new_git_repository-workspace_file_content">workspace_file_content</a>)
```

Clone an external git repository.

Clones a Git repository, checks out the specified branch, tag, or commit, and
makes its targets available for binding. If no branch, tag or commit is
specified, check out the repository's default branch. Also determine the id
and date of the commit that was checked out, and return a dict with
parameters that provide a reproducible version of this rule (which a tag or
branch not necessarily is).

Bazel will first try to perform a shallow fetch of only the specified commit.
If that fails (usually due to missing server support), it will fall back to a
full fetch of the repository.

Prefer [`http_archive`](https://bazel.build/versions/8.9.0/rules/lib/repo/http#http_archive) to `git_repository`.
The reasons are:

* Git repository rules depend on system `git(1)` whereas the HTTP downloader is built
  into Bazel and has no system dependencies.
* `http_archive` supports a list of `urls` as mirrors, and `git_repository` supports only
  a single `remote`.
* `http_archive` works with the [repository cache](https://bazel.build/versions/8.9.0/run/build.md#repository-cache), but not
  `git_repository`. See
  [#5116](https://github.com/bazelbuild/bazel/issues/5116) for more information.

**ATTRIBUTES**

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <tbody>
    <tr id="new_git_repository-name">
      <td>`name`</td>

      <td>
        [Name](https://bazel.build/versions/8.9.0/concepts/labels.md#target-names); required

        A unique name for this repository.
      </td>
    </tr>

    <tr id="new_git_repository-branch">
      <td>`branch`</td>

      <td>
        String; optional

        branch in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified.
      </td>
    </tr>

    <tr id="new_git_repository-build_file">
      <td>`build_file`</td>

      <td>
        [Label](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        The file to use as the BUILD file for this repository.This attribute is an absolute label (use '@//' for the main repo). The file does not need to be named BUILD, but can be (something like BUILD.new-repo-name may work well for distinguishing it from the repository's actual BUILD files.
      </td>
    </tr>

    <tr id="new_git_repository-build_file_content">
      <td>`build_file_content`</td>

      <td>
        String; optional

        The content for the BUILD file for this repository.
      </td>
    </tr>

    <tr id="new_git_repository-canonical_id">
      <td>`canonical_id`</td>

      <td>
        String; optional

        A canonical ID of the file downloaded.

        If specified and non-empty, Bazel will not take the file from cache, unless it
        was added to the cache by a request with the same canonical ID.

        If unspecified or empty, Bazel by default uses the URLs of the file as the
        canonical ID. This helps catch the common mistake of updating the URLs without
        also updating the hash, resulting in builds that succeed locally but fail on
        machines without the file in the cache. This behavior can be disabled with
        \--repo\_env=BAZEL\_HTTP\_RULES\_URLS\_AS\_DEFAULT\_CANONICAL\_ID=0.
      </td>
    </tr>

    <tr id="new_git_repository-commit">
      <td>`commit`</td>

      <td>
        String; optional

        specific commit to be checked out. Precisely one of branch, tag, or commit must be specified.
      </td>
    </tr>

    <tr id="new_git_repository-init_submodules">
      <td>`init_submodules`</td>

      <td>
        Boolean; optional

        Whether to clone submodules in the repository.
      </td>
    </tr>

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

      <td>
        List of strings; optional

        The arguments given to the patch tool. Defaults to -p0 (see the `patch_strip` attribute), however -p1 will usually be needed for patches generated by git. If multiple -p arguments are specified, the last one will take effect.If arguments other than -p are specified, Bazel will fall back to use patch command line tool instead of the Bazel-native patch implementation. When falling back to patch command line tool and patch\_tool attribute is not specified, `patch` will be used.
      </td>
    </tr>

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

      <td>
        List of strings; optional

        Sequence of Bash commands to be applied on Linux/Macos after patches are applied.
      </td>
    </tr>

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

      <td>
        List of strings; optional

        Sequence of Powershell commands to be applied on Windows after patches are applied. If this attribute is not set, patch\_cmds will be executed on Windows, which requires Bash binary to exist.
      </td>
    </tr>

    <tr id="new_git_repository-patch_strip">
      <td>`patch_strip`</td>

      <td>
        Integer; optional

        When set to `N`, this is equivalent to inserting `-pN` to the beginning of `patch_args`.
      </td>
    </tr>

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

      <td>
        String; optional

        The patch(1) utility to use. If this is specified, Bazel will use the specified patch tool instead of the Bazel-native patch implementation.
      </td>
    </tr>

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

      <td>
        [List of labels](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        A list of files that are to be applied as patches after extracting the archive. By default, it uses the Bazel-native patch implementation which doesn't support fuzz match and binary patch, but Bazel will fall back to use patch command line tool if `patch_tool` attribute is specified or there are arguments other than `-p` in `patch_args` attribute.
      </td>
    </tr>

    <tr id="new_git_repository-recursive_init_submodules">
      <td>`recursive_init_submodules`</td>

      <td>
        Boolean; optional

        Whether to clone submodules recursively in the repository.
      </td>
    </tr>

    <tr id="new_git_repository-remote">
      <td>`remote`</td>

      <td>
        String; required

        The URI of the remote Git repository
      </td>
    </tr>

    <tr id="new_git_repository-remote_module_file_integrity">
      <td>`remote_module_file_integrity`</td>

      <td>
        String; optional

        For internal use only.
      </td>
    </tr>

    <tr id="new_git_repository-remote_module_file_urls">
      <td>`remote_module_file_urls`</td>

      <td>
        List of strings; optional

        For internal use only.
      </td>
    </tr>

    <tr id="new_git_repository-remote_patch_strip">
      <td>`remote_patch_strip`</td>

      <td>
        Integer; optional

        The number of leading slashes to be stripped from the file name in the remote patches.
      </td>
    </tr>

    <tr id="new_git_repository-remote_patches">
      <td>`remote_patches`</td>

      <td>
        [Dictionary: String -> String](https://bazel.build/versions/8.9.0/rules/lib/dict); optional

        A map of patch file URL to its integrity value, they are applied after cloning the repository and before applying patch files from the `patches` attribute. It uses the Bazel-native patch implementation, you can specify the patch strip number with `remote_patch_strip`
      </td>
    </tr>

    <tr id="new_git_repository-repo_mapping">
      <td>`repo_mapping`</td>

      <td>
        [Dictionary: String -> String](https://bazel.build/versions/8.9.0/rules/lib/dict); optional

        In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

        For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

        This attribute is *not* supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).
      </td>
    </tr>

    <tr id="new_git_repository-shallow_since">
      <td>`shallow_since`</td>

      <td>
        String; optional

        an optional date, not after the specified commit; the argument is not allowed if a tag or branch is specified (which can always be cloned with --depth=1). Setting such a date close to the specified commit may allow for a shallow clone of the repository even if the server does not support shallow fetches of arbitrary commits. Due to bugs in git's --shallow-since implementation, using this attribute is not recommended as it may result in fetch failures.
      </td>
    </tr>

    <tr id="new_git_repository-sparse_checkout_file">
      <td>`sparse_checkout_file`</td>

      <td>
        [Label](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        File containing .gitignore-style patterns for a sparse checkout of files in this repository. Either `sparse_checkout_patterns` or `sparse_checkout_file` may be specified, or neither, but not both.
      </td>
    </tr>

    <tr id="new_git_repository-sparse_checkout_patterns">
      <td>`sparse_checkout_patterns`</td>

      <td>
        List of strings; optional

        Sequence of patterns for a sparse checkout of files in this repository.
      </td>
    </tr>

    <tr id="new_git_repository-strip_prefix">
      <td>`strip_prefix`</td>

      <td>
        String; optional

        A directory prefix to strip from the extracted files.
      </td>
    </tr>

    <tr id="new_git_repository-tag">
      <td>`tag`</td>

      <td>
        String; optional

        tag in the remote repository to checked out. Precisely one of branch, tag, or commit must be specified.
      </td>
    </tr>

    <tr id="new_git_repository-verbose">
      <td>`verbose`</td>

      <td>
        Boolean; optional
      </td>
    </tr>

    <tr id="new_git_repository-workspace_file">
      <td>`workspace_file`</td>

      <td>
        [Label](https://bazel.build/versions/8.9.0/concepts/labels.md); optional

        No-op attribute; do not use.
      </td>
    </tr>

    <tr id="new_git_repository-workspace_file_content">
      <td>`workspace_file_content`</td>

      <td>
        String; optional

        No-op attribute; do not use.
      </td>
    </tr>
  </tbody>
</table>

**ENVIRONMENT VARIABLES**

This repository rule depends on the following environment variables:

* `BAZEL_HTTP_RULES_URLS_AS_DEFAULT_CANONICAL_ID`


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