# 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](../../gazelle-reference.md) for a general command-line reference.

## Directives

The Go extension defines the following directives.

**Directive:** `# gazelle:go_generate_proto true|false`<br>
**Default:** `true`<br>
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`<br>
**Default:** n/a<br>
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:

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

**Directive:** `# gazelle:go_test default|file`<br>
**Default:** `default`<br>
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,...`<br>
**Default:** `@io_bazel_rules_go//proto:go_proto,@io_bazel_rules_go//proto:go_grpc_v2`<br>
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](https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#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`<br>
**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`<br>
**Default:** `import`<br>
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`<br>
**Default:** `@io_bazel_rules_go//proto:go_proto`<br>
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](https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#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`<br>
**Default:** see below<br>
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`<br>
**Default:** n/a<br>
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`<br>
**Default:** n/a<br>
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`<br>
**Default:** `external`<br>
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](#dependency-resolution).

**Flag:** `-go_grpc_compiler=label`<br>
**Default:** `@io_bazel_rules_go//proto:go_proto,@io_bazel_rules_go//proto:go_grpc_v2`<br>
The protocol buffers compiler to use for building go bindings for gRPC. May be repeated. See [Predefined plugins](https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#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`<br>
**Default:** inferred<br>
Controls the names of generated Go targets. Equivalent to the `# gazelle:go_naming_convention` directive. See details in [Directives](#directives) below.

**Flag:** `-go_naming_convention_external`<br>
**Default:** `import`<br>
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`<br>
**Default:** n/a<br>
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`<br>
**Default:** `@io_bazel_rules_go//proto:go_proto`<br>
The protocol buffers compiler to use for building go bindings. May be repeated. See [Predefined plugins](https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#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`<br>
**Default:** n/a<br>
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

```bash
# 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`<br>
**Default:** n/a<br>
Import repositories from a file as [`go_repository`](reference.md#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`<br>
**Default:** inferred<br>
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`<br>
**Default:** n/a<br>
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`<br>
**Default:** `false`<br>
When true, Gazelle will remove [`go_repository`](reference.md#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,...`<br>
**Default:** n/a<br>
Sets the `build_directives attribute` for the generated [`go_repository`](reference.md#go_repository) rule(s).

**Flag:** `-build_external=external|vendored`<br>
**Default:** n/a<br>
Sets the `build_external` attribute for the generated [`go_repository`](reference.md#go_repository) rule(s).

**Flag:** `-build_extra_args=arg1,arg2,...`<br>
**Default:** n/a<br>
Sets the `build_extra_args attribute` for the generated [`go_repository`](reference.md#go_repository) rule(s).

**Flag:** `-build_file_generation=auto|on|off|clean`<br>
**Default:** n/a<br>
Sets the `build_file_generation` attribute for the generated [`go_repository`](reference.md#go_repository) rule(s).

**Flag:** `-build_file_names=file1,file2,...`<br>
**Default:** n/a<br>
Sets the `build_file_name` attribute for the generated [`go_repository`](reference.md#go_repository) rule(s).

**Flag:** `-build_file_proto_mode=default|package|legacy|disable|disable_global`<br>
**Default:** n/a<br>
Sets the `build_file_proto_mode` attribute for the generated [`go_repository`](reference.md#go_repository) rule(s).

**Flag:** `-build_tags=tag1,tag2,...`<br>
**Default:** n/a<br>
Sets the `build_tags` attribute for the generated [`go_repository`](reference.md#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.