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

# Intro to Gazelle

> Intro to Gazelle, the Bazel tool that visits source trees, reads directives, and generates or merges BUILD files non-destructively while preserving #keep edits.

Gazelle descends from Glaze, a tool built internally at Google to make Go easier to adopt with Bazel (Glaze is to Blaze as Gazelle is to Bazel). Because Go's import semantics were designed with Bazel in mind, resolving import statements to the packages that export them was straightforward — making it a natural fit for automation.

Gazelle was built and long maintained by Jay Conrod at Google, and is now community-maintained at [bazel-contrib/bazel-gazelle](https://github.com/bazel-contrib/bazel-gazelle) — part of bazel-contrib, a Bazel Technical Steering Committee organized under the Linux Foundation.

## Basics

BUILD files are “bare facts” that describe the source code and its dependencies. These facts are mostly trivial to derive from the source code itself. So why force engineers to write these by hand?

At a high level, it operates following the [Visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern):

1. Walk the source tree like Bazel does, respecting `.bazelignore` and similar config.
2. When descending into a directory, read any `BUILD` file's “directive” comments for configuration.
3. Locate source files of interest, typically by file extension.
4. Declare Bazel targets and their import/export edges.
   * Which targets to generate is determined by the source files found and language configuration.
   * Imports are found by parsing import statements — similar to how an IDE's language server works.
   * Exports are usually inferred from file paths or package declarations in source files.
5. After the walk, resolve target imports to Bazel labels and write them into attributes like `deps`.
6. Merge updates into the `BUILD` file, or create one if the directory had none.

This is non-destructive: hand-edits to the `BUILD` file are preserved.

To opt-out of Gazelle managing a syntax element, use the `#keep` comment, for example:

```python theme={null}
py_library(
    name = "keeps",
    # Don't manage this attribute at all
    # keep
    srcs = glob(["*.py"]),
    deps = [
        # Don't remove this even if it seems unused
        "@pypi//some-pkg:pkg",  # keep
    ],
)

# Leave this entire rule alone
# keep
js_library(
    name = "ignore",
    srcs = glob(["*.mjs"]),
)
```

<Note>The bazel-gazelle repo also has some Go-specifics, like the `go_repository` rule, which runs Gazelle on third-party Go packages to generate their BUILD files dynamically.</Note>