{"id":17526553,"url":"https://github.com/bazel-contrib/bazel-gazelle","last_synced_at":"2026-04-07T20:01:54.063Z","repository":{"id":37385077,"uuid":"112655189","full_name":"bazel-contrib/bazel-gazelle","owner":"bazel-contrib","description":"Gazelle is a Bazel build file generator for Bazel projects. It natively supports Go and protobuf, and it may be extended to support new languages and custom rule sets.","archived":false,"fork":false,"pushed_at":"2026-04-05T20:17:40.000Z","size":10145,"stargazers_count":1386,"open_issues_count":451,"forks_count":426,"subscribers_count":35,"default_branch":"master","last_synced_at":"2026-04-05T20:21:39.429Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bazel-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"open_collective":"bazel-rules-authors-sig"}},"created_at":"2017-11-30T20:08:09.000Z","updated_at":"2026-04-05T19:19:55.000Z","dependencies_parsed_at":"2023-10-27T19:28:51.598Z","dependency_job_id":"0ef61c32-bb47-42c8-b62e-bddfe579c63e","html_url":"https://github.com/bazel-contrib/bazel-gazelle","commit_stats":{"total_commits":814,"total_committers":181,"mean_commits":4.497237569060774,"dds":0.7678132678132679,"last_synced_commit":"7d10bf7befce477f518056cfc502939000bea3fa"},"previous_names":["bazelbuild/bazel-gazelle"],"tags_count":77,"template":false,"template_full_name":null,"purl":"pkg:github/bazel-contrib/bazel-gazelle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Fbazel-gazelle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Fbazel-gazelle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Fbazel-gazelle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Fbazel-gazelle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bazel-contrib","download_url":"https://codeload.github.com/bazel-contrib/bazel-gazelle/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bazel-contrib%2Fbazel-gazelle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31526666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-20T15:02:00.779Z","updated_at":"2026-04-07T20:01:54.057Z","avatar_url":"https://github.com/bazel-contrib.png","language":"Go","funding_links":["https://opencollective.com/bazel-rules-authors-sig"],"categories":["Go"],"sub_categories":[],"readme":"# Gazelle build file generator\n\nGazelle is a build file generator for Bazel projects. It can create new BUILD.bazel files for a project that follows language conventions, and it can update existing build files to include new sources, dependencies, and options. Gazelle natively supports Go and protobuf, and it may be [extended](extend.md) to support new languages and custom rule sets.\n\nGazelle may be run by Bazel using the [`gazelle` rule](#bazel-rule) or it may be installed and run as a command line tool. Gazelle can also generate build files for external repositories as part of the [`go_repository`](reference.md#go_repository) rule.\n\n*Gazelle is under active development. Its interface and the rules it generates may change. Gazelle is not an official Google product.*\n\nMailing list: [bazel-go-discuss](https://groups.google.com/forum/#!forum/bazel-go-discuss)\n\nSlack: [#go on Bazel Slack](https://bazelbuild.slack.com/archives/CDBP88Z0D), [#bazel on Go Slack](https://gophers.slack.com/archives/C1SCQE54N)\n\n*rules_go and Gazelle are getting community maintainers! If you are a regular\nuser of either project and are interested in helping out with development,\ncode reviews, and issue triage, please drop by our Slack channels (linked above)\nand say hello!*\n\n**See also:**\n\n* [How Gazelle Works](how-gazelle-works.md)\n* [`go_repository`](reference.md#go_repository)\n* [Extending Gazelle](extend.md)\n* [Avoiding conflicts with proto rules](https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#avoiding-conflicts)\n\n## Supported languages\n\nGazelle can generate Bazel BUILD files for many languages:\n\n* **Go:** Go supported is included here in bazel-gazelle, see below.\n* **Haskell:**  Tweag's [rules_haskell](https://github.com/tweag/rules_haskell) has two extensions: [gazelle_cabal](https://github.com/tweag/gazelle_cabal), for generating rules from Cabal files, and [gazelle_haskell_modules](https://github.com/tweag/gazelle_haskell_modules) for even more fine-grained build definitions.\n* **Java:** bazel-contrib's [rules_jvm](https://github.com/bazel-contrib/rules_jvm) extensions include [a gazelle extension](https://github.com/bazel-contrib/rules_jvm/tree/main/java/gazelle) for generating `java_library`, `java_binary`, `java_test`, and `java_test_suite` rules.\n* **JavaScript / TypeScript:** Aspect provides [JavaScript and TypeScript Support](https://github.com/aspect-build/aspect-gazelle/tree/main/language/js). BenchSci's [rules_nodejs_gazelle](https://github.com/benchsci/rules_nodejs_gazelle) supports generating `ts_project`, `js_library`, `jest_test`, and `web_asset` rules, and is able to support module bundlers like Webpack and Next.js.\n* **Kotlin:** Aspect Build provides some [Kotlin Support](https://github.com/aspect-build/aspect-gazelle/tree/main/language/kotlin). Still under development, please check the README for currently available features.\n* **Protocol Buffers:** Support for the `proto_library` rule. Language-specific rules like `go_proto_library` are supported by other language extensions.\n* **Python:** [rules_python](https://github.com/bazel-contrib/rules_python) has an extension for generating `py_library`, `py_binary`, and `py_test` rules.\n* **R:** [rules_r](https://github.com/grailbio/rules_r) has an extension for generating rules for R package builds and tests.\n* **Rust:** [gazelle_rust](https://github.com/Calsign/gazelle_rust) is an extension for generating [rules_rust](https://github.com/bazelbuild/rules_rust) targets.\n* **Starlark:** [bazel-skylib](https://github.com/bazelbuild/bazel-skylib) has an extension for generating `bzl_library` rules. See [bazel_skylib/gazelle/bzl](https://github.com/bazelbuild/bazel-skylib/tree/main/gazelle/bzl).\n* **Swift:** [swift_gazelle_plugin](https://github.com/cgrindel/swift_gazelle_plugin) has an extension for generating `swift_library`, `swift_binary`, and   `swift_test` rules. It also includes facilities for resolving, downloading and building external Swift packages for a Bazel workspace.\n* **C/C++:** [gazelle_cc](https://github.com/EngFlow/gazelle_cc) has an extension for `cc_*` rules.\n\nIf you know of an extension which could be linked here, please [open a PR](https://github.com/bazel-contrib/bazel-gazelle/edit/master/README.rst)!\n\nMore languages can be added by [Extending Gazelle](extend.md). Chat with us in the `#gazelle` channel on [Bazel Slack](https://slack.bazel.build) if you'd like to discuss your design.\n\nIf you've written your own extension, please consider open-sourcing it for use by the rest of the community. Note that such extensions belong in a language-specific repository, not in bazel-gazelle. See discussion in [#1030](https://github.com/bazelbuild/bazel-gazelle/issues/1030).\n\n## Setup\n\n### Bzlmod\n\nSee the [Go Bzlmod docs](https://github.com/bazel-contrib/rules_go/blob/master/docs/go/core/bzlmod.md).\n\nThe full documentation for the `go_deps` extension is in [extensions.md](extensions.md#go_deps).\n\n### WORKSPACE\n\nTo use Gazelle in a new project, add the `bazel_gazelle` repository and its dependencies to your WORKSPACE file and call `gazelle_dependencies`. It should look like this:\n\n```bzl\nload(\"@bazel_tools//tools/build_defs/repo:http.bzl\", \"http_archive\")\n\nhttp_archive(\n    name = \"io_bazel_rules_go\",\n    integrity = \"sha256-M6zErg9wUC20uJPJ/B3Xqb+ZjCPn/yxFF3QdQEmpdvg=\",\n    urls = [\n        \"https://mirror.bazel.build/github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip\",\n        \"https://github.com/bazelbuild/rules_go/releases/download/v0.48.0/rules_go-v0.48.0.zip\",\n    ],\n)\n\nhttp_archive(\n    name = \"bazel_gazelle\",\n    integrity = \"sha256-12v3pg/YsFBEQJDfooN6Tq+YKeEWVhjuNdzspcvfWNU=\",\n    urls = [\n        \"https://mirror.bazel.build/github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz\",\n        \"https://github.com/bazelbuild/bazel-gazelle/releases/download/v0.37.0/bazel-gazelle-v0.37.0.tar.gz\",\n    ],\n)\n\n\nload(\"@io_bazel_rules_go//go:deps.bzl\", \"go_register_toolchains\", \"go_rules_dependencies\")\nload(\"@bazel_gazelle//:deps.bzl\", \"gazelle_dependencies\", \"go_repository\")\n\n############################################################\n# Define your own dependencies here using go_repository.\n# Else, dependencies declared by rules_go/gazelle will be used.\n# The first declaration of an external repository \"wins\".\n############################################################\n\ngo_rules_dependencies()\n\ngo_register_toolchains(version = \"1.20.5\")\n\ngazelle_dependencies()\n```\n\n`gazelle_dependencies` supports optional argument `go_env` (dict-mapping)\nto set project specific go environment variables. If you are using a\n`WORKSPACE.bazel` file, you will need to specify that using:\n\n```bzl\ngazelle_dependencies(go_repository_default_config = \"//:WORKSPACE.bazel\")\n```\n\nAdd the code below to the BUILD or BUILD.bazel file in the root directory\nof your repository.\n\n**Important:** For Go projects, replace the string after `prefix` with\nthe portion of your import path that corresponds to your repository.\n\n```bzl\nload(\"@bazel_gazelle//:def.bzl\", \"gazelle\")\n\n# gazelle:prefix github.com/example/project\ngazelle(name = \"gazelle\")\n```\n\nAfter adding this code, you can run Gazelle with Bazel.\n\n```\nbazel run //:gazelle\n```\n\nThis will generate new BUILD.bazel files for your project. You can run the same command in the future to update existing BUILD.bazel files to include new source files or options.\n\nYou can write other `gazelle` rules to run alternate commands like `update-repos`.\n\n```bzl\ngazelle(\n    name = \"gazelle-update-repos\",\n    args = [\n        \"-from_file=go.mod\",\n        \"-to_macro=deps.bzl%go_dependencies\",\n        \"-prune\",\n    ],\n    command = \"update-repos\",\n)\n```\n\nYou can also pass additional arguments to Gazelle after a `--` argument.\n\n```\nbazel run //:gazelle -- update-repos -from_file=go.mod -to_macro=deps.bzl%go_dependencies\n```\n\nAfter running `update-repos`, you might want to run `bazel run //:gazelle` again, as the `update-repos` command can affect the output of a normal run of Gazelle.\n\nTo verify that all BUILD files are update-to-date, you can use the `gazelle_test` rule.\n\n```\nload(\"@bazel_gazelle//:def.bzl\", \"gazelle_test\")\n\ngazelle_test(\n    name = \"gazelle_test\",\n    workspace = \"//:BUILD.bazel\", # a file in the workspace root, where the gazelle will be run\n)\n```\n\nHowever, please note that gazelle_test cannot be cached.\n\n## Usage\n\n### Command line\n\nIn most cases, you'll invoke Gazelle through Bazel using the `gazelle` rule:\n\n```\nbazel run //:gazelle\n```\n\nTo run Gazelle in specific directories, or with additional flags:\n\n```\nbazel run //:gazelle -- [flags...] [directories...]\n```\n\nIf you build and install a Gazelle binary, you can also invoke it directly without `bazel run`.\n\n```\ngazelle [fix|update] [flags...] [directories...]\n```\n\n### Configuration directives\n\nGazelle can be configured with *directives*, which are written as top-level comments in build files. Most options that can be set on the command line can also be set using directives. Some options can only be set with directives.\n\nDirective comments have the form `# gazelle:key value`. For example:\n\n```bzl\nload(\"@io_bazel_rules_go//go:def.bzl\", \"go_library\")\n\n# gazelle:prefix github.com/example/project\n# gazelle:build_file_name BUILD,BUILD.bazel\n\ngo_library(\n    name = \"go_default_library\",\n    srcs = [\"example.go\"],\n    importpath = \"github.com/example/project\",\n    visibility = [\"//visibility:public\"],\n)\n```\n\nDirectives apply in the directory where they are set *and* in subdirectories. This means, for example, if you set `# gazelle:prefix` in the build file in your project's root directory, it affects your whole project. If you set it in a subdirectory, it only affects rules in that subtree.\n\n### Reference\n\nFor a full reference on Gazelle's configuration directives, flags, and rules, see the following pages:\n\n- [Configuration and command line reference](gazelle-reference.md)\n- [Go reference](language/go/reference.md)\n- [Proto reference](language/proto/reference.md)\n- [Rule reference](reference.md) (for `gazelle` and `gazelle_binary` rules)\n\nExtensions defined outside this repo provide their own references.\n\n### Lazy indexing in `fix` and `update`\n\nBy default, `fix` and `update` read all build files in a repo to build an index of library rules (see [Dependency resolution](#dependency-resolution)) when Gazelle starts. This can take a long time on a large repo. To avoid this problem, Gazelle can lazily index specific directories, with help from extensions that support lazy indexing.\n\nTo configure lazy indexing with Go, add `go_search` directives like this:\n\n```bzl\n# gazelle:go_search third_party/go\n# gazelle:go_search replace/b example.com/b\n```\n\nThese directives point to directories that contain Go code outside the current module, with an optional package prefix. `go_search` directives are not necessary if you're following regular Go module conventions or are using a Go `vendor` directory.\n\nTo configure lazy indexing with protobuf, add `proto_search` directives like this:\n\n```bzl\n# gazelle:proto_search third_party/proto api\n```\n\nThe two arguments are a prefix to remove from the import path and a prefix to add. These correspond to the [`strip_import_prefix`](https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.strip_import_prefix) and [`import_prefix`](https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library.import_prefix) attributes of [`proto_library`](https://bazel.build/reference/be/protocol-buffer#proto_library). They tell Gazelle how to transform an import path read from a .proto source file into a repo-root-relative path to a directory that may contain the imported file.\n\nTo use Gazelle with lazy indexing, run with `-r=false -index=lazy`, and pass the directories to update on the command line.\n\n```bzl\ngazelle -r=false -index=lazy path/to/dir1 path/to/dir2\n```\n\nYou can configure your `gazelle` Bazel target to pass these flags automatically:\n\n```bzl\nload(\"@gazelle//:def.bzl\", \"gazelle\", \"gazelle_binary\")\n\ngazelle(\n    name = \"gazelle\",\n    command = \"fix\",\n    extra_args = [\"-r=false\", \"-index=lazy\"],\n    gazelle = \":gazelle_binary\",\n)\n\ngazelle_binary(\n    name = \"gazelle_binary\",\n    ...\n)\n```\n\n## Compatibility with Go\n\nGazelle is compatible with supported releases of Go, per the [Go Release Policy](https://golang.org/doc/devel/release.html#policy). The Go Team officially supports the current and previous minor releases. Older releases are not supported and don't receive bug fixes or security updates.\n\nGazelle may use language and library features from the oldest supported release.\n\n## Dependency resolution\n\nOne of Gazelle's most important jobs is resolving library import strings (like `import \"golang.org/x/sys/unix\"`) to Bazel labels (like `@org_golang_x_sys//unix:go_default_library`). Gazelle follows the rules below to resolve dependencies:\n\n1. If the import to be resolved is part of a standard library, no explicit dependency is written. For example, in Go, you don't need to declare that you depend on `\"fmt\"`.\n1. If a `# gazelle:resolve` directive matches the import to be resolved, the label at the end of the directive will be used.\n1. If proto rule generation is enabled, special rules will be used when importing certain libraries. These rules may be disabled by adding `# gazelle:proto disable_global` to a build file (this will affect subdirectories, too) or by passing `-proto disable_global` on the command line.\n    1. Imports of Well Known Types are mapped to rules in `@io_bazel_rules_go//proto/wkt`.\n    1. Imports of `github.com/golang/protobuf/ptypes`, `descriptor`, and `jsonpb` are mapped to special rules in `@com_github_golang_protobuf`. See [Avoiding conflicts with proto rules](https://github.com/bazel-contrib/rules_go/blob/master/proto/core.rst#avoiding-conflicts).\n1. If the import to be resolved is in the library index, the import will be resolved to that library. If `-index=all`, Gazelle builds an index of library rules in the current repository before starting dependency resolution. This can take a while, since Gazelle visits every directory in the repository. If `-index=lazy`, then language extensions may hint at specific directories to visit, which can be much faster.\n    1. For Go, the match is based on the `importpath` attribute.\n    1. For proto, the match is based on the `srcs` attribute.\n1. If `-index=none` and a package is imported that has the current `go_prefix` as a prefix, Gazelle generates a label following a convention. For example, if the build file in `//src` set the prefix with `# gazelle:prefix example.com/repo/foo`, and you import the library `\"example.com/repo/foo/bar`, the dependency will be `\"//src/foo/bar:go_default_library\"`.\n1. Otherwise, Gazelle will use the current `external` mode to resolve the dependency.\n    1. In `external` mode (the default), Gazelle will transform the import string into an external repository label. For example, `\"golang.org/x/sys/unix\"` would be resolved to `\"@org_golang_x_sys//unix:go_default_library\"`. Gazelle does not confirm whether the external repository is actually declared in WORKSPACE, but if there *is* a `go_repository` in WORKSPACE with a matching `importpath`, Gazelle will use its name. Gazelle does not index rules in external repositories, so it's possible the resolved dependency does not exist.\n    1. In `static` mode, Gazelle has the same behavior as `external` mode, except that it will not call out to the network for resolution when no matching import is found within WORKSPACE. Instead, it will skip the unknown import. This is the default mode for `go_repository` rules.\n    1. In `vendored` mode, Gazelle will transform the import string into a label in the vendor directory. For example, `\"golang.org/x/sys/unix\"` would be resolved to `\"//vendor/golang.org/x/sys/unix:go_default_library\"`. This mode is usually not necessary, since vendored libraries will be indexed and resolved using rule 4.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazel-contrib%2Fbazel-gazelle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbazel-contrib%2Fbazel-gazelle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbazel-contrib%2Fbazel-gazelle/lists"}