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

# Configuration

> Learn how Gazelle directives configure Bazel BUILD files, including gazelle:exclude, gazelle:map_kind, and gazelle:resolve for dependency resolution.

## Directives

These are special comments that are placed anywhere in a `BUILD` file. They govern behavior as the generator visits files beneath this folder. Sub-packages can override the settings of their parent folder.

### Built-in

Some directives are built-in to Gazelle, while others are specific to an extension. Unfortunately, some of the built-in directives are specific to Go, which is just a historical accident since it originally was written for Go.

Here are some important ones to know:

* `# gazelle:exclude pattern` Prevents Gazelle from processing a file or directory if the given [doublestar.Match](https://github.com/bmatcuk/doublestar#match) pattern matches.

* `# gazelle:map_kind from_kind to_kind to_kind_load` Customizes the kind of rules generated by Gazelle. Most commonly, this would be used to replace the rules provided by a ruleset with custom macros. For example, using a custom macro instead of `go_library`:

  ```
  # gazelle:map_kind go_library go_lib //tools/go:defs.bzl
  ```

* `# gazelle:resolve source-lang [import-lang] import-string label` Specifies an explicit mapping from an import string to a label for [Dependency resolution](https://github.com/bazel-contrib/bazel-gazelle#dependency-resolution). For example, a go import of `example.com/foo` resolving to a target in `//foo`

  ```
  # gazelle:resolve go example.com/foo //foo:my_go_library
  ```

* `# gazelle:resolve_regexp source-lang [import-lang] import-string-regexp label` Like `resolve`, but matches imports against an [RE2](https://github.com/google/re2/wiki/Syntax) regular expression instead of an exact string — handy for mapping a whole namespace at once. Subpattern captures can be referenced in the label as `$1`, `$2`, etc.

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

* `# gazelle:generation_mode create_and_update|update_only` Controls whether Gazelle creates new `BUILD` files or only updates existing ones. The default (`create_and_update`) creates new files. Setting it to `update_only` is useful when adopting Gazelle incrementally — Gazelle will update packages you've already onboarded but won't touch directories that don't yet have a `BUILD` file.

  ```
  # gazelle:generation_mode update_only
  ```

### Per-language

Individual extensions can add their own, for example, the python extension has its own directives:

[Python Directives](https://rules-python.readthedocs.io/en/latest/gazelle/docs/index.html)

And the JavaScript extension from Aspect does as well:

[JavaScript Directives](https://github.com/aspect-build/aspect-gazelle/blob/main/language/js/README.md#directives)

### Avoiding the need for directives

Directives are required when the source code doesn’t sufficiently describe what Gazelle needs to do. An alternative approach is to introduce load-bearing syntax in the source code. This way the information about the dependency graph stays in source files, not magic comments in `BUILD` files.

As one example, you can use [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) in TypeScript to declare “ambient” library dependencies:

* `/// <reference path="..." />` This directive is the most common of this group. It serves as a declaration of *dependency* between files.
* `/// <reference lib="..." />` This directive allows a file to explicitly include an existing built-in *lib* file.

Of course, the Gazelle extension that reads the source file has to have logic that parses this syntax and uses it to inform dependency resolution or updates to attributes.