# bazel-contrib/bazel-gazelle architecture

> Architecture diagram of the GitHub repository bazel-contrib/bazel-gazelle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bazel-contrib/bazel-gazelle
- Repository: https://github.com/bazel-contrib/bazel-gazelle

## Overview

Gazelle is a command-line tool and extensible library for creating and updating Bazel BUILD files. Its principal workflow accepts a workspace and command, walks project directories, generates language-specific rules, resolves imports against an index, and merges results into BUILD files. Go and protobuf are native generators; external extensions add other languages. The tree also contains repository-rule utilities and a compatibility layer for the v1/v2 APIs. The update orchestrator and several subsystems are unsampled, so their internal connections are shown only where documented or marked unverified.

Main entry points: [`v2/cmd/gazelle/update`](https://github.com/bazel-contrib/bazel-gazelle/tree/master/v2/cmd/gazelle/update) (Update orchestrator), [`v2/language/lang.go`](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/language/lang.go) (Language lifecycle), [`rule/rule.go`](https://github.com/bazel-contrib/bazel-gazelle/blob/master/rule/rule.go) (Rule model), [`cmd/gazelle/main.go`](https://github.com/bazel-contrib/bazel-gazelle/blob/master/cmd/gazelle/main.go) (Gazelle CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entrypoints"]
  node_cli["Gazelle CLI<br/>[main.go]"]
  node_update["Update orchestrator"]
end

subgraph group_engine["Generation engine"]
  node_walker["Workspace walker<br/>[walk.go]"]
  node_v2lang["Language lifecycle<br/>[lang.go]"]
  node_index["Import index<br/>[index.go]"]
  node_rules["Rule model<br/>[rule.go]"]
  node_merger["BUILD merger<br/>[merger.go]"]
  node_v2label["v2 label utilities<br/>[label.go]"]
  node_v2merger["v2 merger<br/>[merger.go]"]
  node_v2walker["v2 walker<br/>[walk.go]"]
end

subgraph group_languages["Language support"]
  node_go["Go generator<br/>[generate.go]"]
  node_proto["Proto generator<br/>[generate.go]"]
  node_compat["API compatibility<br/>[compat.go]"]
end

subgraph group_utilities["Repository utilities"]
  node_remote["Remote repository cache<br/>[remote.go]"]
  node_repo_config["Repository config tool<br/>[main.go]"]
  node_override["Override generator<br/>[main.go]"]
  node_release["Release utility<br/>[main.go]"]
end

node_user(("Workspace operator"))
node_buildfiles["BUILD files"]
node_extensions["Language extensions"]

node_user -->|"runs"| node_cli
node_cli -->|"dispatches"| node_update
node_update -.->|"walks workspace"| node_walker
node_update -.->|"runs lifecycle"| node_v2lang
node_update -.->|"resolves imports"| node_index
node_update -.->|"merges updates"| node_merger
node_go -->|"implements"| node_v2lang
node_proto -->|"implements"| node_v2lang
node_extensions -->|"extends"| node_v2lang
node_update -.->|"generates rules"| node_go
node_update -.->|"generates rules"| node_proto
node_index -.->|"consults cache"| node_remote
node_merger -->|"merges rules"| node_rules
node_update -->|"updates"| node_buildfiles
node_compat -->|"adapts APIs"| node_v2lang
node_repo_config -->|"lists repositories"| node_remote
node_override -->|"builds overrides"| node_rules
node_release -->|"rewrites rules"| node_rules
node_v2merger -->|"operates on rules"| node_rules
node_v2walker -->|"walks rule data"| node_rules
node_v2label -.->|"path helpers"| node_v2walker

click node_cli "https://github.com/bazel-contrib/bazel-gazelle/blob/master/cmd/gazelle/main.go"
click node_update "https://github.com/bazel-contrib/bazel-gazelle/tree/master/v2/cmd/gazelle/update"
click node_walker "https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/walk/walk.go"
click node_v2lang "https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/language/lang.go"
click node_index "https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/resolve/index.go"
click node_rules "https://github.com/bazel-contrib/bazel-gazelle/blob/master/rule/rule.go"
click node_merger "https://github.com/bazel-contrib/bazel-gazelle/blob/master/merger/merger.go"
click node_go "https://github.com/bazel-contrib/bazel-gazelle/blob/master/language/go/generate.go"
click node_proto "https://github.com/bazel-contrib/bazel-gazelle/blob/master/language/proto/generate.go"
click node_compat "https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/compat/compat.go"
click node_remote "https://github.com/bazel-contrib/bazel-gazelle/blob/master/repo/remote.go"
click node_repo_config "https://github.com/bazel-contrib/bazel-gazelle/blob/master/cmd/generate_repo_config/main.go"
click node_override "https://github.com/bazel-contrib/bazel-gazelle/blob/master/tools/override-generator/main.go"
click node_release "https://github.com/bazel-contrib/bazel-gazelle/blob/master/tools/releaser/main.go"
click node_v2label "https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/label/label.go"
click node_v2merger "https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/merger/merger.go"
click node_v2walker "https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/walk/walk.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_update toneBlue
class node_walker,node_v2lang,node_index,node_rules,node_merger,node_v2label,node_v2merger,node_v2walker toneAmber
class node_go,node_proto,node_compat toneMint
class node_remote,node_repo_config,node_override,node_release toneRose
class node_user,node_buildfiles,node_extensions toneIndigo
```

## Components

### Command entrypoints

- [Gazelle CLI](https://github.com/bazel-contrib/bazel-gazelle/blob/master/cmd/gazelle/main.go): `cmd/gazelle/main.go`
- [Update orchestrator](https://github.com/bazel-contrib/bazel-gazelle/tree/master/v2/cmd/gazelle/update): `v2/cmd/gazelle/update`

### Generation engine

- [Workspace walker](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/walk/walk.go): `v2/walk/walk.go`
- [Language lifecycle](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/language/lang.go): `v2/language/lang.go`
- [Import index](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/resolve/index.go): `v2/resolve/index.go`
- [Rule model](https://github.com/bazel-contrib/bazel-gazelle/blob/master/rule/rule.go): `rule/rule.go`
- [BUILD merger](https://github.com/bazel-contrib/bazel-gazelle/blob/master/merger/merger.go): `merger/merger.go`
- [v2 label utilities](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/label/label.go): `v2/label/label.go`
- [v2 merger](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/merger/merger.go): `v2/merger/merger.go`
- [v2 walker](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/walk/walk.go): `v2/walk/walk.go`

### Language support

- [Go generator](https://github.com/bazel-contrib/bazel-gazelle/blob/master/language/go/generate.go): `language/go/generate.go`
- [Proto generator](https://github.com/bazel-contrib/bazel-gazelle/blob/master/language/proto/generate.go): `language/proto/generate.go`
- [API compatibility](https://github.com/bazel-contrib/bazel-gazelle/blob/master/v2/compat/compat.go): `v2/compat/compat.go`

### Repository utilities

- [Remote repository cache](https://github.com/bazel-contrib/bazel-gazelle/blob/master/repo/remote.go): `repo/remote.go`
- [Repository config tool](https://github.com/bazel-contrib/bazel-gazelle/blob/master/cmd/generate_repo_config/main.go): `cmd/generate_repo_config/main.go`
- [Override generator](https://github.com/bazel-contrib/bazel-gazelle/blob/master/tools/override-generator/main.go): `tools/override-generator/main.go`
- [Release utility](https://github.com/bazel-contrib/bazel-gazelle/blob/master/tools/releaser/main.go): `tools/releaser/main.go`

### Other components

- **Workspace operator**
- **BUILD files**
- **Language extensions**

## Connections

- Workspace operator → Gazelle CLI: runs
- Gazelle CLI → Update orchestrator: dispatches (evidence: `cmd/gazelle/main.go`)
- Update orchestrator → Workspace walker: walks workspace
- Update orchestrator → Language lifecycle: runs lifecycle
- Update orchestrator → Import index: resolves imports
- Update orchestrator → BUILD merger: merges updates
- Go generator → Language lifecycle: implements (evidence: `language/go/generate.go`)
- Proto generator → Language lifecycle: implements (evidence: `language/proto/generate.go`)
- Language extensions → Language lifecycle: extends
- Update orchestrator → Go generator: generates rules
- Update orchestrator → Proto generator: generates rules
- Import index → Remote repository cache: consults cache
- BUILD merger → Rule model: merges rules (evidence: `merger/merger.go`)
- Update orchestrator → BUILD files: updates
- API compatibility → Language lifecycle: adapts APIs (evidence: `v2/compat/compat.go`)
- Repository config tool → Remote repository cache: lists repositories (evidence: `cmd/generate_repo_config/main.go`)
- Override generator → Rule model: builds overrides (evidence: `tools/override-generator/main.go`)
- Release utility → Rule model: rewrites rules (evidence: `tools/releaser/main.go`)
- v2 merger → Rule model: operates on rules (evidence: `v2/merger/merger.go`)
- v2 walker → Rule model: walks rule data (evidence: `v2/walk/walk.go`)
- v2 label utilities → v2 walker: path helpers