Configuration and command line reference

This page describes Gazelle's general-purpose commands, directives, and flags. Language-specific directives and flags are described on separate pages. See Go and proto for extensions defined in this repo.

Usage

gazelle <command> [flags...] [directories...]

The first argument to Gazelle may be one of the commands below. If no command is specified, update is assumed. The remaining arguments are specific to each command and are documented below.

update: Scans sources files, then generates and updates build files.
fix: Same as the update command, but it also fixes deprecated usage of rules.
update-repos: Adds and updates repository rules in the WORKSPACE file.

`fix` and `update`

The update command is the most common way of running Gazelle. Gazelle scans sources in directories throughout the repository, then creates and updates build files.

The fix command does everything update does, but it also fixes deprecated usage of rules, analogous to go fix. For example, cgo_library will be consolidated with go_library. This command may delete or rename rules, so it's not used by default. The transformations are documented with each language extension: see Go and proto for details.

Both commands accept a list of directories to process as positional arguments. If no directories are specified, Gazelle will process the current directory. Subdirectories will be processed recursively by default (unless -r=false).

Flags

The following general purpose flags are accepted. See Go: Flags and Proto: Flags for flags defined by language extensions in this repo.

Many flags have equivalent directives that may be written in BUIlD files rather than passed on the command line. When possible, use directives instead of flags. Directives are more consistent and readable for developers working on a project, and they are more precise, since they can be set in specific subdirectories.

Flag: -build_file_name=file1,file2,...
Default: BUILD.bazel,BUILD
Comma-separated list of file names. Gazelle recognizes these files as Bazel build files. New files will use the first name in this list. Use this if your project contains non-Bazel files named BUILD (or build on case-insensitive file systems).

Flag: -build_tags=tag1,tag2,...
Default: n/a
List of Go build tags Gazelle will defer to Bazel for evaluation. Gazelle applies constraints when generating Go rules. It assumes certain tags are true on certain platforms (for example, amd64,linux). It assumes all Go release tags are true (for example, go1.8). It considers other tags to be false (for example, ignore). This flag allows custom tags to be evaluated by Bazel at build time. Bazel may still filter sources with these tags. Use bazel build --define gotags=foo,bar to set tags at build time.

Flag: -exclude=pattern
Default: n/a
Prevents Gazelle from processing a file or directory if the given doublestar.Match pattern matches. If the pattern refers to a source file, Gazelle won‘t include it in any rules. If the pattern refers to a directory, Gazelle won’t recurse into it. This option may be repeated. Patterns must be slash-separated, relative to the repository root. This is equivalent to the # gazelle:exclude pattern directive.

Flag: -index=none|lazy|all
Default: all
Determines whether Gazelle should index the libraries in the current repository and whether it should use the index to resolve dependencies.

If none or false, indexing is disabled, and Gazelle relies purely on conventions to translate language-specific import strings into dependency labels.

If lazy, Gazelle indexes libraries in directories it visits explicitly. Language extensions may be configured to index additional directories through directives like # gazelle:go_search. This mode is very fast when recursion is disabled with -r=false.

If all or true, Gazelle indexes all directories in the repository, even when recursion is disabled. This makes dependency resolution simple but can be slow for large repositories.

Flag: -mode=fix|print|diff
Default: fix
Method for emitting merged build files.

In fix mode, Gazelle writes generated and merged files to disk.
In print mode, Gazelle prints updated files to stdout and does not write files to disk.
In diff mode, Gazelle prints a unified diff to stdout and does not write files to disk.

Flag: -r
Default: true
Controls whether Gazelle recurses into subdirectories of the directories named on the command line. This is enabled by default, so when Gazelle is run from the repository root directory without arguments, it visits and updates all directories. This can be slow for large repositories.

When recursion is disabled, Gazelle only visits specific named directories. This can be very fast, but you may also want to use lazy indexing (-index=lazy) or disable indexing altogether (-index=none).

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: -remove_noop_keep_comments
Default: false
Whether Gazelle will remove # keep comments when the thing being kept would have been kept without the comment. This is always enabled when run with the fix command, and for the update command must be specified. This will only remove # keep comments targeting list items, e.g. not rules, entire lists/dicts, or dict items.

Flag: -lang=lang1,lang2
Default: n/a
Selects languages for which to compose and index rules. By default, all languages that this Gazelle was built with are processed.

Flag: -cpuprofile=filename
Default: n/a
If specified, gazelle uses runtime/pprof to collect CPU profiling information from the command and save it to the given file. By default, this is disabled.

Flag: -memprofile=filename
Default: n/a
If specified, gazelle uses runtime/pprof to collect memory a profile information from the command and save it to a file. By default, this is disabled.

`update-repos`

The update-repos command updates Go repository rules in Bazel's WORKSPACE mode. See Go: update-repos for details.

Directives

Gazelle 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.

Directive comments have the form # gazelle:key value. For example:

load("@io_bazel_rules_go//go:def.bzl", "go_library")

# gazelle:prefix github.com/example/project
# gazelle:build_file_name BUILD,BUILD.bazel

go_library(
    name = "go_default_library",
    srcs = ["example.go"],
    importpath = "github.com/example/project",
    visibility = ["//visibility:public"],
)

Directives 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.

The following general-purpose directives are recognized. See Go: Directives and Proto: Directives for directives defined by language extensions in this repo.

Directive: # gazelle:alias_kind macro_name wrapped_kind
Default: n/a
Denotes that a macro aliases / wraps a given rule.

If you have a wrapper macro around a rule that gazelle knows how to update the attrs for, the alias_kind directive will instruct gazelle that it should treat the particular marco like the underlying wrapped kind.

alias_kind is different from the map_kind directive in that it does not force the rule to be generated as the wrapped kind. Instead, it just instructs gazelle that it should index and update the attrs for rules that match the macro.

For example, if you use # gazelle:alias_kind my_foo_binary foo_binary, Gazelle will still generate foo_binary targets when generating new targets from new source files. It is up to a person to update the foo_binary targets to my_foo_binary targets. Once this manual step is done, Gazelle will continue to update the my_foo_binary targets as if they were foo_binary targets.

Wrapper macros are commonly used to handle common boilerplate or to add deploy/release verbs, as described in the bazel Verbs Tutorial.

Directive: # gazelle:build_file_names name1,name2...
Default: BUILD.bazel,BUILD
Comma-separated list of file names. Gazelle recognizes these files as Bazel build files. New files will use the first name in this list. Use this if your project contains non-Bazel files named BUILD (or build on case-insensitive file systems).

Directive: # gazelle:build_tags foo,bar
Default: n/a
List of Go build tags Gazelle will defer to Bazel for evaluation. Gazelle applies constraints when generating Go rules. It assumes certain tags are true on certain platforms (for example, amd64,linux). It assumes all Go release tags are true (for example, go1.8). It considers other tags to be false (for example, ignore). This flag allows custom tags to be evaluated by Bazel at build time. Bazel may still filter sources with these tags. Use bazel build --define gotags=foo,bar to set tags at build time.

Directive: # gazelle:directive_file path
Default: n/a
Loads additional Gazelle directives from an external file. The path is relative to the directory containing the build file. The external file uses the same # gazelle:key value format as build file directives. Blank lines and comment lines that do not match the directive pattern are ignored.

Directives from the external file are inserted at the position of the directive_file entry, so inline directives appearing after directive_file can override values from the file. This is useful for managing large numbers of directives (e.g., resolve overrides) in a separate, possibly generated file.

Recursive use is not supported: a directive file may not itself contain a directive_file entry.

For example, with the following build file:

# gazelle:directive_file gazelle_resolve.cfg
# gazelle:resolve go example.com/local //local:lib

And gazelle_resolve.cfg:

# gazelle:resolve go example.com/foo //third_party:foo
# gazelle:resolve go example.com/bar //third_party:bar

Gazelle will process the three resolve directives as if they were all written inline in the build file, with example.com/local last (highest precedence).

Directive: # gazelle:exclude pattern
Default: n/a
Prevents Gazelle from processing a file or directory if the given doublestar.Match pattern matches. If the pattern refers to a source file, Gazelle won‘t include it in any rules. If the pattern refers to a directory, Gazelle won’t recurse into it. This directive may be repeated to exclude multiple patterns, one per line.

Directive: # gazelle:follow pattern
Default: n/a
Instructs Gazelle to follow a symbolic link to a directory within the repository if the given doublestar.Match pattern matches. Normally, Gazelle does not follow symbolic links unless they point outside of the repository root. Care must be taken to avoid visiting a directory more than once. The # gazelle:exclude directive may be used to prevent Gazelle from recursing into a directory.

Directive: # gazelle:generation_mode create_and_update|update_only
Default: create_and_update
Declares if gazelle should create and update BUILD files per directory or only update existing BUILD files. Valid values are: create_and_update and update_only.

Directive: # gazelle:ignore
Default: n/a
Prevents Gazelle from modifying the build file. Gazelle will still read rules in the build file and may modify build files in subdirectories.

Directive: # gazelle:map_kind from_kind to_kind to_kind_load
Default: n/a
Customizes the kind of rules generated by Gazelle.

As a separate step after generating rules, any new rules of kind from_kind have their kind replaced with to_kind. This means that to_kind must accept the same parameters and behave similarly.

Most commonly, this would be used to replace the rules provided by rules_go with custom macros. For example, gazelle:map_kind go_binary go_deployable //tools/go:def.bzl would configure Gazelle to produce rules of kind go_deployable as loaded from //tools/go:def.bzl instead of go_binary, for this directory or within.

Existing rules of the old kind will be ignored. To switch your codebase from a builtin kind to a mapped kind, use buildozer.

Directive: # gazelle:resolve source-lang [import-lang] import-string label
Default: n/a
Specifies an explicit mapping from an import string to a label for Dependency resolution. Accepts the following arguments:

source-lang is the language of the source code being imported.
import-lang (optional) is the language importing the library. This is usually the same as source-lang but may differ with generated code. For example, when resolving dependencies for a go_proto_library, source-lang would be "proto" and import-lang would be "go". import-lang may be omitted if it is the same as source-lang.
import-string is the string used in source code to import a library.
label is the Bazel label that Gazelle should write in deps.

For example:

# gazelle:resolve go example.com/foo //foo:go_default_library
# gazelle:resolve proto go foo/foo.proto //foo:foo_go_proto

Directive: # gazelle:resolve_regexp source-lang import-lang import-string-regexp label
Default: n/a
Specifies an explicit mapping from an import regex to a label for Dependency resolution. Accepts the following arguments:

source-lang is the language of the source code being imported.
import-lang (optional) is the language importing the library. This is usually the same as source-lang but may differ with generated code. For example, when resolving dependencies for a go_proto_library, source-lang would be "proto" and import-lang would be "go". import-lang may be omitted if it is the same as source-lang.
import-string-regex is the regex applied to the import in the source code. If it matches, that import will be resolved to the label specified below.
label is the Bazel label that Gazelle should write in deps. The label can be constructed using captured strings from the subpattern matching in import-string-regex.

For example:

# gazelle:resolve_regexp go example.com/.* //foo:go_default_library
# gazelle:resolve_regexp proto go foo/.*\.proto //foo:foo_go_proto
# gazelle:resolve_regexp proto go foo/(.*)\.proto //foo/$1:foo_rule_proto

Directive: # gazelle:lang lang1,lang2
Default: n/a
Sets the language selection flag for this and descendent packages, which causes gazelle to index and generate rules for only the languages named in this directive.

Directive: # gazelle:default_visibility visibility
Default: n/a
Comma-separated list of visibility specifications. This directive adds the visibility specifications for this and descendant packages. For example:

# gazelle:default_visibility //foo:__subpackages__,//src:__subpackages__

You must include the extension @gazelle//language/bazel/visibility to use this directive.

`WORKSPACE` directives

Gazelle also reads directives from the WORKSPACE file. They may be used to discover custom repository names and known prefixes. The fix and update commands use these directives for dependency resolution. update-repos uses them to learn about repository rules defined in alternate locations.

Directive: # gazelle:repository rule_kind attr1_name=attr1_value,...
Default: n/a
Specifies a repository rule that Gazelle should know about. The directive can be repeated multiple times, and can be declared from within a macro definition that Gazelle knows about. At the very least the directive must define a rule kind and a name attribute, but it can define extra attributes after that.

This is useful for teaching Gazelle about repos declared in external macros. The directive can also be used to override an actual repository rule. For example, a git_repository rule for org_golang_x_tools could be overriden with the directive:

# gazelle:repository go_repository name=org_golang_x_tools importpath=golang.org/x/tools

Gazelle would then proceed as if org_golang_x_tools was declared as a go_repository rule.

Directive: # gazelle:repository_macro [+]macroFile%defName
Default: n/a
Tells Gazelle to look for repository rules in a macro in a .bzl file. The directive can be repeated multiple times. The macro can be generated by calling update-repos with the to_macro flag. The directive can be prepended with a +, which will tell Gazelle to also look for repositories within any macros called by the specified macro.

`keep` comments

In addition to directives, Gazelle supports # keep comments that protect parts of build files from being modified. # keep may be written before a rule, before an attribute, or after a string within a list.

# keep comments might take one of 2 forms; the # keep literal or a description prefixed by # keep:.

For example, sppose you have a library that includes a generated .go file. Gazelle won't know what imports to resolve, so you may need to add dependencies manually with # keep comments.

load("@io_bazel_rules_go//go:def.bzl", "go_library")
load("@com_github_example_gen//:gen.bzl", "gen_go_file")

gen_go_file(
    name = "magic",
    srcs = ["magic.go.in"],
    outs = ["magic.go"],
)

go_library(
    name = "go_default_library",
    srcs = ["magic.go"],
    visibility = ["//visibility:public"],
    deps = [
        "@com_github_example_gen//:go_default_library",  # keep
        "@com_github_example_gen//a/b/c:go_default_library",  # keep: this is also important
    ],
)

Configuration and command line reference

Usage

fix and update

Flags

update-repos

Directives

WORKSPACE directives

keep comments

`fix` and `update`

`update-repos`

`WORKSPACE` directives

`keep` comments