reference.md

Go Reference

This page describes the directives and flags defined by Gazelle's Go extension. It also describes the update-repos command, which is specific to Go. See Configuration and command line reference for a general command-line reference.

Directives

The Go extension defines the following directives.

Directive: # gazelle:go_generate_proto true|false
Default: true
Instructs Gazelle's Go extension whether to generate go_proto_library rules for proto_library rules generated by the Proto extension. When this directive is true Gazelle will generate go_proto_library and go_library according to # gazelle:proto. When this directive is false, the Go extension will ignore any proto_library rules. If there are any pre-generated Go files, they will be treated as regular Go files.

Directive: # gazelle:go_search dir prefix
Default: n/a
When lazy indexing is enabled (-index=lazy), this directive tells Gazelle about additional directories containing Go libraries that should be indexed for dependency resolution. Specific directories are indexed as needed based on Go import directives seen.

The dir argument is a slash-separated path relative to the directory containing the build file. The prefix argument is optional. It indicates a Go prefix for the named directory, which is useful for nested modules or module replacement directories.

go_search may be used multiple times. Each setting adds to the search path for the current directory and subdirectories. If go_search is used without arguments, it clears the current list of search paths.

As an example, suppose you have a vendor directory with a non-standard name, third_party/go, and a module replacement directory replace/b. You can index these directories with:

# gazelle:go_search third_party/go
# gazelle:go_search replace/b example.com/b

Directive: # gazelle:go_test default|file
Default: default
Tells Gazelle how to generate rules for _test.go files. Valid values are:

• default: One go_test rule will be generated whose srcs includes all _test.go files in the directory.
• file: A distinct go_test rule will be generated for each _test.go file in the package directory.

Directive: # gazelle:go_grpc_compilers compiler1,compiler2,...
Default: @io_bazel_rules_go//proto:go_proto,@io_bazel_rules_go//proto:go_grpc_v2
The protocol buffers compiler(s) to use for building go bindings for gRPC. Multiple compilers, separated by commas, may be specified. Omit the directive value to reset go_grpc_compilers back to the default. See Predefined plugins for available options; commonly used options include @io_bazel_rules_go//proto:gofast_grpc and @io_bazel_rules_go//proto:gogofaster_grpc.

Directive: # gazelle:go_naming_convention mode
Default: inferred Controls the names of generated Go targets. Valid values are:

• go_default_library: Library targets are named go_default_library, test targets are named go_default_test.
• import: Library and test targets are named after the last segment of their import path. For example, example.repo/foo is named foo, and the test target is foo_test. Major version suffixes like /v2 are dropped. For a main package with a binary foobin, the names are instead foobin_lib and foobin_test.
• import_alias: Same as import, but an alias target is generated named go_default_library to ensure backwards compatibility.

If no naming convention is set, Gazelle attempts to infer the convention in use by reading the root build file and build files in immediate subdirectories. If no Go targets are found, Gazelle defaults to import.

Directive: # gazelle:go_naming_convention_external
Default: import
Controls the default naming convention used when resolving libraries in external repositories with unknown naming conventions. Accepts the same values as go_naming_convention.

Directive: # gazelle:go_proto_compilers
Default: @io_bazel_rules_go//proto:go_proto
The protocol buffers compiler(s) to use for building go bindings. Multiple compilers, separated by commas, may be specified. Omit the directive value to reset go_proto_compilers back to the default. See Predefined plugins for available options; commonly used options include @io_bazel_rules_go//proto:gofast_proto and @io_bazel_rules_go//proto:gogofaster_proto.

Directive: # gazelle:importpath_prefix
Default: see below
A prefix for importmap attributes in Go library rules. Gazelle will set an importmap on a go_library or go_proto_library by concatenating this with the relative path from the directory where the prefix is set to the library. For example, if importmap_prefix is set to "x/example.com/repo" in the build file //foo/bar:BUILD.bazel, then a library in foo/bar/baz will have the importmap of "x/example.com/repo/baz".

importmap is not set when it matches importpath.

As a special case, when Gazelle enters a directory named vendor, it sets importmap_prefix to a string based on the repository name and the location of the vendor directory. If you wish to override this, you'll need to set importmap_prefix explicitly in the vendor directory.

Directive: # gazelle:prefix path
Default: n/a
A prefix for importpath attributes on library rules. Gazelle will set an importpath on a go_library or go_proto_library by concatenating this with the relative path from the directory where the prefix is set to the library. Most commonly, prefix is set to the name of a repository in the root directory of a repository. For example, in this repository, prefix is set in //:BUILD.bazel to github.com/bazelbuild/bazel-gazelle. The go_library in //cmd/gazelle is assigned the importpath "github.com/bazelbuild/bazel-gazelle/cmd/gazelle".

As a special case, when Gazelle enters a directory named vendor, it sets prefix to the empty string. This automatically gives vendored libraries an intuitive importpath.

Directive: # gazelle:go_visibility label
Default: n/a
By default, internal packages are only visible to its siblings. This directive adds a label internal packages should be visible to additionally. This directive can be used several times, adding a list of labels.

Flags

Flag: -external=external|static|vendored
Default: external
Determines how Gazelle resolves Go import paths that cannot be resolved in the current repository. May be :value:external, :value:static or :value:vendored. See Dependency resolution.

Flag: -go_grpc_compiler=label
Default: @io_bazel_rules_go//proto:go_proto,@io_bazel_rules_go//proto:go_grpc_v2
The protocol buffers compiler to use for building go bindings for gRPC. May be repeated. See Predefined plugins for available options; commonly used options include @io_bazel_rules_go//proto:gofast_grpc and @io_bazel_rules_go//proto:gogofaster_grpc.

Flag: -go_naming_convention
Default: inferred
Controls the names of generated Go targets. Equivalent to the # gazelle:go_naming_convention directive. See details in Directives below.

Flag: -go_naming_convention_external
Default: import
Controls the default naming convention used when resolving libraries in external repositories with unknown naming conventions. Equivalent to the # gazelle:go_naming_convention_external directive.

Flag: -go_prefix=example.com/repo
Default: n/a
A prefix of import paths for Go libraries in the repository that corresponds to the repository root. Equivalent to setting the # gazelle:prefix directive in the root BUILD.bazel file or the prefix attribute of the gazelle rule. If neither of those are set, this option is mandatory. This prefix is used to determine whether an import path refers to a library in the current repository or an external dependency.

Flag: -go_proto_compiler=label
Default: @io_bazel_rules_go//proto:go_proto
The protocol buffers compiler to use for building go bindings. May be repeated. See Predefined plugins for available options; commonly used options include @io_bazel_rules_go//proto:gofast_proto and @io_bazel_rules_go//proto:gogofaster_proto.

Flag: -known_import=example.com
Default: n/a
Skips Go import path resolution for a known domain. May be repeated.

When Gazelle resolves an import path to an external dependency, it attempts to discover the remote repository root over HTTP. Gazelle skips this discovery step for a few well-known domains with predictable structure, like golang.org and github.com. This flag specifies additional domains to skip, which is useful in situations where the lookup would fail for some reason.

update-repos

The update-repos command updates repository rules. It can write the rules to either the WORKSPACE (by default) or a .bzl file macro function. It can be used to add new repository rules or update existing rules to the specified version. It can also import repository rules from a go.mod or a go.work file.

WARNING: This command is mainly used for managing external Go dependencies in Bazel's WORKSPACE mode. For managing external Go dependencies in Bazel's BzlMod mode, please check: https://github.com/bazelbuild/rules_go/blob/master/docs/go/core/bzlmod.md#external-dependencies

# Add or update a repository to latest version by import path
$ gazelle update-repos example.com/new/repo

# Add or update a repository to specified version/commit by import path
$ gazelle update-repos example.com/new/repo@v1.3.1

# Import repositories from go.mod
$ gazelle update-repos -from_file=go.mod

# Import repositories from go.work
$ gazelle update-repos -from_file=go.work

# Import repositories from go.mod and update macro
$ gazelle update-repos -from_file=go.mod -to_macro=repositories.bzl%go_repositories

# Import repositories from go.work and update macro
$ gazelle update-repos -from_file=go.work -to_macro=repositories.bzl%go_repositories

The following flags are accepted:

Flag: -from_file=lock-file
Default: n/a
Import repositories from a file as go_repository rules. These rules will be added to the bottom of the WORKSPACE file or merged with existing rules. The lock file format is inferred from the file name. go.mod and go.work are all supported.

Flag: -repo_root=dir
Default: inferred
The root directory of the repository. Gazelle normally infers this to be the directory containing the WORKSPACE file. Gazelle will not process packages outside this directory.

Flag: -to_macro=macroFile%defName
Default: n/a
Tells Gazelle to write new repository rules into a .bzl macro function rather than the WORKSPACE file. The repository_macro directive should be added to the WORKSPACE in order for future Gazelle calls to recognize the repos defined in the macro file.

Flag: -prune
Default: false
When true, Gazelle will remove go_repository rules that no longer have equivalent repos in the go.mod file. This flag can only be used with -from_file.

Flag: -build_directives=arg1,arg2,...
Default: n/a
Sets the build_directives attribute for the generated go_repository rule(s).

Flag: -build_external=external|vendored
Default: n/a
Sets the build_external attribute for the generated go_repository rule(s).

Flag: -build_extra_args=arg1,arg2,...
Default: n/a
Sets the build_extra_args attribute for the generated go_repository rule(s).

Flag: -build_file_generation=auto|on|off|clean
Default: n/a
Sets the build_file_generation attribute for the generated go_repository rule(s).

Flag: -build_file_names=file1,file2,...
Default: n/a
Sets the build_file_name attribute for the generated go_repository rule(s).

Flag: -build_file_proto_mode=default|package|legacy|disable|disable_global
Default: n/a
Sets the build_file_proto_mode attribute for the generated go_repository rule(s).

Flag: -build_tags=tag1,tag2,...
Default: n/a
Sets the build_tags attribute for the generated go_repository rule(s).

fix command transformation

The Go extension can fix deprecated usages of rules_go. Some transformations are safe and are applied whether the fix or update command is used. Others are potentially destructive and are only applied when the fix command is used.

The following transformations are performed:

Migrate library to embed (fix and update): Gazelle replaces library attributes with embed attributes.

Migrate gRPC compilers (fix and update): Gazelle converts go_grpc_library rules to go_proto_library rules with compilers = ["@io_bazel_rules_go//proto:go_proto", "@io_bazel_rules_go//proto:go_grpc_v2"].

Flatten srcs (fix and update): Gazelle converts srcs attributes that use OS and architecture-specific select expressions to flat lists. rules_go filters these sources anyway.

Squash cgo libraries (fix only): Gazelle will remove cgo_library rules named cgo_default_library and merge their attributes with a go_library rule in the same package named go_default_library. If no such go_library rule exists, a new one will be created. Other cgo_library rules will not be removed.

Squash external tests (fix only): Gazelle will squash go_test rules named go_default_xtest into go_default_test. Earlier versions of rules_go required internal and external tests to be built separately, but this is no longer needed.

Remove legacy protos (fix only): Gazelle will remove usage of go_proto_library rules loaded from @io_bazel_rules_go//proto:go_proto_library.bzl and filegroup rules named go_default_library_protos. Newly generated proto rules will take their place. Since filegroup isn't needed anymore and go_proto_library has different attributes and was always written by hand, Gazelle will not attempt to merge anything from these rules with the newly generated rules.

This transformation is only applied in the default proto mode. Since Gazelle will run in legacy proto mode if go_proto_library.bzl is loaded, this transformation is not usually applied. You can set the proto mode explicitly using the directive # gazelle:proto default.

Update loads of gazelle rule (fix and update): Gazelle will remove loads of gazelle from @io_bazel_rules_go//go:def.bzl. It will automatically add a load from @bazel_gazelle//:def.bzl if gazelle is not loaded from another location.