table fix (#2083)
I accidentally broke the table in
https://github.com/bazel-contrib/bazel-gazelle/pull/2071
So here is a fix to extend the existing table with a few additional
columns.
After this, Github should render the file correctly.
Note: markdown would have been a bit easier with table syntax.
diff --git a/README.rst b/README.rst
index 8f43438..1b071d5 100644
--- a/README.rst
+++ b/README.rst
@@ -483,169 +483,169 @@
The following flags are accepted:
-+-------------------------------------------------------------------+----------------------------------------+
-| **Name** | **Default value** |
-+===================================================================+========================================+
-| :flag:`-build_file_name file1,file2,...` | :value:`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` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| 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` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| 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:`-external external|static|vendored` | :value:`external` |
-+-------------------------------------------------------------------+----------------------------------------+
-| Determines how Gazelle resolves import paths that cannot be resolve in the |
-| current repository. May be :value:`external`, :value:`static` or :value:`vendored`. See |
-| `Dependency resolution`_. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-index none|lazy|all` | :value:`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:`-go_grpc_compiler` | ``@io_bazel_rules_go//proto:go_grpc_v2`` |
-+-------------------------------------------------------------------+----------------------------------------+
-| The protocol buffers compiler to use for building go bindings for gRPC. May be repeated. |
-| |
-| See `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` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| Controls the names of generated Go targets. Equivalent to the |
-| ``# gazelle:go_naming_convention`` directive. See details in |
-| `Directives`_ below. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-go_naming_convention_external` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| 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` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| A prefix of import paths for 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` | ``@io_bazel_rules_go//proto:go_proto`` |
-+-------------------------------------------------------------------+----------------------------------------+
-| The protocol buffers compiler to use for building go bindings. May be repeated. |
-| |
-| See `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` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| Skips 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. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-mode fix|print|diff` | :value:`fix` |
-+-------------------------------------------------------------------+----------------------------------------+
-| Method for emitting merged build files. |
-| |
-| In ``fix`` mode, Gazelle writes generated and merged files to disk. In |
-| ``print`` mode, it prints them to stdout. In ``diff`` mode, it prints a |
-| unified diff. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-proto default|file|package|legacy|disable|disable_global` | :value:`default` |
-+-------------------------------------------------------------------+----------------------------------------+
-| Determines how Gazelle should generate rules for .proto files. See details |
-| in `Directives`_ below. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-proto_group group` | :value:`""` |
-+-------------------------------------------------------------------+----------------------------------------+
-| Determines the proto option Gazelle uses to group .proto files into rules |
-| when in ``package`` mode. See details in `Directives`_ below. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-proto_import_prefix path` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| Sets the `import_prefix`_ attribute of generated ``proto_library`` rules. |
-| This adds a prefix to the string used to import ``.proto`` files listed in |
-| the ``srcs`` attribute of generated rules. Equivalent to the |
-| ``# gazelle:proto_import_prefix`` directive. See details in `Directives`_ below. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-r` | :value:`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` | |
-+-------------------------------------------------------------------+----------------------------------------+
-| 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:`-lang lang1,lang2,...` | :value:`""` |
-+-------------------------------------------------------------------+----------------------------------------+
-| Selects languages for which to compose and index rules. |
-| |
-| By default, all languages that this Gazelle was built with are processed. |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-cpuprofile filename` | :value:`""` |
-+-------------------------------------------------------------------+----------------------------------------+
-| If specified, gazelle uses [runtime/pprof](https://pkg.go.dev/runtime/pprof#StartCPUProfile) to collect |
-| CPU profiling information from the command and save it to the given file. |
-| |
-| By default, this is disabled |
-+-------------------------------------------------------------------+----------------------------------------+
-| :flag:`-memprofile filename` | :value:`""` |
-+-------------------------------------------------------------------+----------------------------------------+
-| If specified, gazelle uses [runtime/pprof](https://pkg.go.dev/runtime/pprof#WriteHeapProfile) to collect |
-| memory a profile information from the command and save it to a file. |
-| |
-| By default, this is disabled |
-+-------------------------------------------------------------------+----------------------------------------+
++-------------------------------------------------------------------+------------------------------------------+
+| **Name** | **Default value** |
++===================================================================+==========================================+
+| :flag:`-build_file_name file1,file2,...` | :value:`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` | |
++-------------------------------------------------------------------+------------------------------------------+
+| 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` | |
++-------------------------------------------------------------------+------------------------------------------+
+| 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:`-external external|static|vendored` | :value:`external` |
++-------------------------------------------------------------------+------------------------------------------+
+| Determines how Gazelle resolves import paths that cannot be resolve in the |
+| current repository. May be :value:`external`, :value:`static` or :value:`vendored`. See |
+| `Dependency resolution`_. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-index none|lazy|all` | :value:`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:`-go_grpc_compiler` | ``@io_bazel_rules_go//proto:go_grpc_v2`` |
++-------------------------------------------------------------------+------------------------------------------+
+| The protocol buffers compiler to use for building go bindings for gRPC. May be repeated. |
+| |
+| See `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` | |
++-------------------------------------------------------------------+------------------------------------------+
+| Controls the names of generated Go targets. Equivalent to the |
+| ``# gazelle:go_naming_convention`` directive. See details in |
+| `Directives`_ below. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-go_naming_convention_external` | |
++-------------------------------------------------------------------+------------------------------------------+
+| 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` | |
++-------------------------------------------------------------------+------------------------------------------+
+| A prefix of import paths for 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` | ``@io_bazel_rules_go//proto:go_proto`` |
++-------------------------------------------------------------------+------------------------------------------+
+| The protocol buffers compiler to use for building go bindings. May be repeated. |
+| |
+| See `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` | |
++-------------------------------------------------------------------+------------------------------------------+
+| Skips 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. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-mode fix|print|diff` | :value:`fix` |
++-------------------------------------------------------------------+------------------------------------------+
+| Method for emitting merged build files. |
+| |
+| In ``fix`` mode, Gazelle writes generated and merged files to disk. In |
+| ``print`` mode, it prints them to stdout. In ``diff`` mode, it prints a |
+| unified diff. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-proto default|file|package|legacy|disable|disable_global` | :value:`default` |
++-------------------------------------------------------------------+------------------------------------------+
+| Determines how Gazelle should generate rules for .proto files. See details |
+| in `Directives`_ below. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-proto_group group` | :value:`""` |
++-------------------------------------------------------------------+------------------------------------------+
+| Determines the proto option Gazelle uses to group .proto files into rules |
+| when in ``package`` mode. See details in `Directives`_ below. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-proto_import_prefix path` | |
++-------------------------------------------------------------------+------------------------------------------+
+| Sets the `import_prefix`_ attribute of generated ``proto_library`` rules. |
+| This adds a prefix to the string used to import ``.proto`` files listed in |
+| the ``srcs`` attribute of generated rules. Equivalent to the |
+| ``# gazelle:proto_import_prefix`` directive. See details in `Directives`_ below. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-r` | :value:`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` | |
++-------------------------------------------------------------------+------------------------------------------+
+| 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:`-lang lang1,lang2,...` | :value:`""` |
++-------------------------------------------------------------------+------------------------------------------+
+| Selects languages for which to compose and index rules. |
+| |
+| By default, all languages that this Gazelle was built with are processed. |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-cpuprofile filename` | :value:`""` |
++-------------------------------------------------------------------+------------------------------------------+
+| If specified, gazelle uses [runtime/pprof](https://pkg.go.dev/runtime/pprof#StartCPUProfile) to collect |
+| CPU profiling information from the command and save it to the given file. |
+| |
+| By default, this is disabled |
++-------------------------------------------------------------------+------------------------------------------+
+| :flag:`-memprofile filename` | :value:`""` |
++-------------------------------------------------------------------+------------------------------------------+
+| If specified, gazelle uses [runtime/pprof](https://pkg.go.dev/runtime/pprof#WriteHeapProfile) to collect |
+| memory a profile information from the command and save it to a file. |
+| |
+| By default, this is disabled |
++-------------------------------------------------------------------+------------------------------------------+
.. _Predefined plugins: https://github.com/bazelbuild/rules_go/blob/master/proto/core.rst#predefined-plugins
@@ -770,338 +770,338 @@
The following directives are recognized:
-+---------------------------------------------------+----------------------------------------+
-| **Directive** | **Default value** |
-+===================================================+========================================+
-| :direc:`# gazelle:build_file_name names` | :value:`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). |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:generation_mode` | ``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``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:build_tags foo,bar` | none |
-+---------------------------------------------------+----------------------------------------+
-| 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:exclude pattern` | 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:follow pattern` | 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:go_generate_proto` | ``true`` |
-+---------------------------------------------------+----------------------------------------+
-| 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:go_test mode` | ``default`` |
-+---------------------------------------------------+----------------------------------------+
-| 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:go_grpc_compilers` | ``@io_bazel_rules_go//proto:go_grpc_v2`` |
-+---------------------------------------------------+----------------------------------------+
-| 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`_ for available options; commonly used options include |
-| ``@io_bazel_rules_go//proto:gofast_grpc`` and |
-| ``@io_bazel_rules_go//proto:gogofaster_grpc``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:go_naming_convention` | inferred automatically |
-+---------------------------------------------------+----------------------------------------+
-| 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``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:go_naming_convention_external` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| Controls the default naming convention used when resolving libraries in |
-| external repositories with unknown naming conventions. Accepts the same values |
-| as ``go_naming_convention``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:go_proto_compilers` | ``@io_bazel_rules_go//proto:go_proto`` |
-+---------------------------------------------------+----------------------------------------+
-| 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`_ for available options; commonly used options include |
-| ``@io_bazel_rules_go//proto:gofast_proto`` and |
-| ``@io_bazel_rules_go//proto:gogofaster_proto``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:ignore` | 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:importmap_prefix path` | See below |
-+---------------------------------------------------+----------------------------------------+
-| A prefix for ``importmap`` attributes in 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. |
-+------------------------------------------------------------+-------------------------------+
-| :direc:`# gazelle:map_kind from_kind to_kind to_kind_load` | 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`_. |
-+------------------------------------------------------------+-------------------------------+
-| :direc:`# gazelle:alias_kind macro_name wrapped_kind` | 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`_. |
-| |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:prefix path` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| 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``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:proto mode` | :value:`default` |
-+---------------------------------------------------+----------------------------------------+
-| Tells Gazelle how to generate rules for .proto files. Valid values are: |
-| |
-| * ``default``: ``proto_library``, ``go_proto_library``, and ``go_library`` |
-| rules are generated using ``@io_bazel_rules_go//proto:def.bzl``. Only one |
-| of each rule may be generated per directory. This is the default mode. |
-| * ``file``: a ``proto_library`` rule is generated for every .proto file. |
-| * ``package``: multiple ``proto_library`` and ``go_proto_library`` rules |
-| may be generated in the same directory. .proto files are grouped into |
-| rules based on their package name or another option (see ``proto_group``). |
-| * ``legacy``: ``filegroup`` rules are generated for use by |
-| ``@io_bazel_rules_go//proto:go_proto_library.bzl``. ``go_proto_library`` |
-| rules must be written by hand. Gazelle will run in this mode automatically |
-| if ``go_proto_library.bzl`` is loaded to avoid disrupting existing |
-| projects, but this can be overridden with a directive. |
-| * ``disable``: .proto files are ignored. Gazelle will run in this mode |
-| automatically if ``go_proto_library`` is loaded from any other source, |
-| but this can be overridden with a directive. |
-| * ``disable_global``: like ``disable`` mode, but also prevents Gazelle from |
-| using any special cases in dependency resolution for Well Known Types and |
-| Google APIs. Useful for avoiding build-time dependencies on protoc. |
-| |
-| This directive applies to the current directory and subdirectories. As a |
-| special case, when Gazelle enters a directory named ``vendor``, if the proto |
-| mode isn't set explicitly in a parent directory or on the command line, |
-| Gazelle will run in ``disable`` mode. Additionally, if the file |
-| ``@io_bazel_rules_go//proto:go_proto_library.bzl`` is loaded, Gazelle |
-| will run in ``legacy`` mode. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:proto_group option` | :value:`""` |
-+---------------------------------------------------+----------------------------------------+
-| *This directive is only effective in* ``package`` *mode (see above).* |
-| |
-| Specifies an option that Gazelle can use to group .proto files into rules. |
-| For example, when set to ``go_package``, .proto files with the same |
-| ``option go_package`` will be grouped together. |
-| |
-| When this directive is set to the empty string, Gazelle will group packages |
-| by their proto package statement. |
-| |
-| Rule names are generated based on the last run of identifier characters |
-| in the package name. For example, if the package is ``"foo/bar/baz"``, the |
-| ``proto_library`` rule will be named ``baz_proto``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:proto_import_prefix path` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| Sets the `import_prefix`_ attribute of generated ``proto_library`` rules. |
-| This adds a prefix to the string used to import ``.proto`` files listed in |
-| the ``srcs`` attribute of generated rules. |
-| |
-| For example, if the target ``//a:b_proto`` has ``srcs = ["b.proto"]`` and |
-| ``import_prefix = "github.com/x/y"``, then ``b.proto`` should be imported |
-| with the string ``"github.com/x/y/a/b.proto"``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:proto_strip_import_prefix path` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| Sets the `strip_import_prefix`_ attribute of generated ``proto_library`` rules. |
-| This is a prefix to strip from the strings used to import ``.proto`` files. |
-| |
-| If the prefix starts with a slash, it's intepreted relative to the repository |
-| root. Otherwise, it's relative to the directory containing the build file. |
-| The package-relative form is only useful when a single build file covers |
-| ``.proto`` files in subdirectories. Gazelle doesn't generate build files like |
-| this, so only paths with a leading slash should be used. Gazelle will print |
-| a warning when the package-relative form is used. |
-| |
-| For example, if the target ``//proto/a:b_proto`` has ``srcs = ["b.proto"]`` |
-| and ``strip_import_prefix = "/proto"``, then ``b.proto`` should be imported |
-| with the string ``"a/b.proto"``. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:resolve ...` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| Specifies an explicit mapping from an import string to a label for |
-| `Dependency resolution`_. The format for a resolve directive is: |
-| |
-| ``# gazelle:resolve source-lang import-lang import-string label`` |
-| |
-| * ``source-lang`` is the language of the source code being imported. |
-| * ``import-lang`` 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: |
-| |
-| .. code:: bzl |
-| |
-| # gazelle:resolve go example.com/foo //foo:go_default_library |
-| # gazelle:resolve proto go foo/foo.proto //foo:foo_go_proto |
-| |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:resolve_regexp ...` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| Specifies an explicit mapping from an import regex to a label for |
-| `Dependency resolution`_. The format for a resolve directive is: |
-| |
-| ``# gazelle:resolve_regexp source-lang import-lang import-string-regex label`` |
-| |
-| * ``source-lang`` is the language of the source code being imported. |
-| * ``import-lang`` 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: |
-| |
-| .. code:: bzl |
-| |
-| # 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 |
-| |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:go_visibility label` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:lang lang1,lang2,...` | 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. |
-+---------------------------------------------------+----------------------------------------+
-| :direc:`# gazelle:default_visibility visibility` | n/a |
-+---------------------------------------------------+----------------------------------------+
-| Comma-separated list of visibility specifications. |
-| This directive adds the visibility specifications for this and descendant packages. |
-| |
-| For example: |
-| |
-| .. code:: bzl |
-| |
-| # gazelle:default_visibility //foo:__subpackages__,//src:__subpackages__ |
-+---------------------------------------------------+----------------------------------------+
++---------------------------------------------------+------------------------------------------+
+| **Directive** | **Default value** |
++===================================================+==========================================+
+| :direc:`# gazelle:build_file_name names` | :value:`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). |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:generation_mode` | ``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``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:build_tags foo,bar` | none |
++---------------------------------------------------+------------------------------------------+
+| 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:exclude pattern` | 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:follow pattern` | 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:go_generate_proto` | ``true`` |
++---------------------------------------------------+------------------------------------------+
+| 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:go_test mode` | ``default`` |
++---------------------------------------------------+------------------------------------------+
+| 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:go_grpc_compilers` | ``@io_bazel_rules_go//proto:go_grpc_v2`` |
++---------------------------------------------------+------------------------------------------+
+| 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`_ for available options; commonly used options include |
+| ``@io_bazel_rules_go//proto:gofast_grpc`` and |
+| ``@io_bazel_rules_go//proto:gogofaster_grpc``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:go_naming_convention` | inferred automatically |
++---------------------------------------------------+------------------------------------------+
+| 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``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:go_naming_convention_external` | n/a |
++---------------------------------------------------+------------------------------------------+
+| Controls the default naming convention used when resolving libraries in |
+| external repositories with unknown naming conventions. Accepts the same values |
+| as ``go_naming_convention``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:go_proto_compilers` | ``@io_bazel_rules_go//proto:go_proto`` |
++---------------------------------------------------+------------------------------------------+
+| 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`_ for available options; commonly used options include |
+| ``@io_bazel_rules_go//proto:gofast_proto`` and |
+| ``@io_bazel_rules_go//proto:gogofaster_proto``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:ignore` | 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:importmap_prefix path` | See below |
++---------------------------------------------------+------------------------------------------+
+| A prefix for ``importmap`` attributes in 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. |
++------------------------------------------------------------+---------------------------------+
+| :direc:`# gazelle:map_kind from_kind to_kind to_kind_load` | 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`_. |
++------------------------------------------------------------+---------------------------------+
+| :direc:`# gazelle:alias_kind macro_name wrapped_kind` | 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`_. |
+| |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:prefix path` | n/a |
++---------------------------------------------------+------------------------------------------+
+| 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``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:proto mode` | :value:`default` |
++---------------------------------------------------+------------------------------------------+
+| Tells Gazelle how to generate rules for .proto files. Valid values are: |
+| |
+| * ``default``: ``proto_library``, ``go_proto_library``, and ``go_library`` |
+| rules are generated using ``@io_bazel_rules_go//proto:def.bzl``. Only one |
+| of each rule may be generated per directory. This is the default mode. |
+| * ``file``: a ``proto_library`` rule is generated for every .proto file. |
+| * ``package``: multiple ``proto_library`` and ``go_proto_library`` rules |
+| may be generated in the same directory. .proto files are grouped into |
+| rules based on their package name or another option (see ``proto_group``). |
+| * ``legacy``: ``filegroup`` rules are generated for use by |
+| ``@io_bazel_rules_go//proto:go_proto_library.bzl``. ``go_proto_library`` |
+| rules must be written by hand. Gazelle will run in this mode automatically |
+| if ``go_proto_library.bzl`` is loaded to avoid disrupting existing |
+| projects, but this can be overridden with a directive. |
+| * ``disable``: .proto files are ignored. Gazelle will run in this mode |
+| automatically if ``go_proto_library`` is loaded from any other source, |
+| but this can be overridden with a directive. |
+| * ``disable_global``: like ``disable`` mode, but also prevents Gazelle from |
+| using any special cases in dependency resolution for Well Known Types and |
+| Google APIs. Useful for avoiding build-time dependencies on protoc. |
+| |
+| This directive applies to the current directory and subdirectories. As a |
+| special case, when Gazelle enters a directory named ``vendor``, if the proto |
+| mode isn't set explicitly in a parent directory or on the command line, |
+| Gazelle will run in ``disable`` mode. Additionally, if the file |
+| ``@io_bazel_rules_go//proto:go_proto_library.bzl`` is loaded, Gazelle |
+| will run in ``legacy`` mode. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:proto_group option` | :value:`""` |
++---------------------------------------------------+------------------------------------------+
+| *This directive is only effective in* ``package`` *mode (see above).* |
+| |
+| Specifies an option that Gazelle can use to group .proto files into rules. |
+| For example, when set to ``go_package``, .proto files with the same |
+| ``option go_package`` will be grouped together. |
+| |
+| When this directive is set to the empty string, Gazelle will group packages |
+| by their proto package statement. |
+| |
+| Rule names are generated based on the last run of identifier characters |
+| in the package name. For example, if the package is ``"foo/bar/baz"``, the |
+| ``proto_library`` rule will be named ``baz_proto``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:proto_import_prefix path` | n/a |
++---------------------------------------------------+------------------------------------------+
+| Sets the `import_prefix`_ attribute of generated ``proto_library`` rules. |
+| This adds a prefix to the string used to import ``.proto`` files listed in |
+| the ``srcs`` attribute of generated rules. |
+| |
+| For example, if the target ``//a:b_proto`` has ``srcs = ["b.proto"]`` and |
+| ``import_prefix = "github.com/x/y"``, then ``b.proto`` should be imported |
+| with the string ``"github.com/x/y/a/b.proto"``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:proto_strip_import_prefix path` | n/a |
++---------------------------------------------------+------------------------------------------+
+| Sets the `strip_import_prefix`_ attribute of generated ``proto_library`` rules. |
+| This is a prefix to strip from the strings used to import ``.proto`` files. |
+| |
+| If the prefix starts with a slash, it's intepreted relative to the repository |
+| root. Otherwise, it's relative to the directory containing the build file. |
+| The package-relative form is only useful when a single build file covers |
+| ``.proto`` files in subdirectories. Gazelle doesn't generate build files like |
+| this, so only paths with a leading slash should be used. Gazelle will print |
+| a warning when the package-relative form is used. |
+| |
+| For example, if the target ``//proto/a:b_proto`` has ``srcs = ["b.proto"]`` |
+| and ``strip_import_prefix = "/proto"``, then ``b.proto`` should be imported |
+| with the string ``"a/b.proto"``. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:resolve ...` | n/a |
++---------------------------------------------------+------------------------------------------+
+| Specifies an explicit mapping from an import string to a label for |
+| `Dependency resolution`_. The format for a resolve directive is: |
+| |
+| ``# gazelle:resolve source-lang import-lang import-string label`` |
+| |
+| * ``source-lang`` is the language of the source code being imported. |
+| * ``import-lang`` 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: |
+| |
+| .. code:: bzl |
+| |
+| # gazelle:resolve go example.com/foo //foo:go_default_library |
+| # gazelle:resolve proto go foo/foo.proto //foo:foo_go_proto |
+| |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:resolve_regexp ...` | n/a |
++---------------------------------------------------+------------------------------------------+
+| Specifies an explicit mapping from an import regex to a label for |
+| `Dependency resolution`_. The format for a resolve directive is: |
+| |
+| ``# gazelle:resolve_regexp source-lang import-lang import-string-regex label`` |
+| |
+| * ``source-lang`` is the language of the source code being imported. |
+| * ``import-lang`` 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: |
+| |
+| .. code:: bzl |
+| |
+| # 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 |
+| |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:go_visibility label` | n/a |
++---------------------------------------------------+------------------------------------------+
+| 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:lang lang1,lang2,...` | 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. |
++---------------------------------------------------+------------------------------------------+
+| :direc:`# gazelle:default_visibility visibility` | n/a |
++---------------------------------------------------+------------------------------------------+
+| Comma-separated list of visibility specifications. |
+| This directive adds the visibility specifications for this and descendant packages. |
+| |
+| For example: |
+| |
+| .. code:: bzl |
+| |
+| # gazelle:default_visibility //foo:__subpackages__,//src:__subpackages__ |
++---------------------------------------------------+------------------------------------------+
Gazelle also reads directives from the WORKSPACE file. They may be used to
discover custom repository names and known prefixes. The ``fix`` and ``update``
