Repository: bazelbuild/bazel
Issue: Can someone elaborate on the instructions to install zsh completion?
Labels: type: documentation (cleanup)
P3
team-Bazel

I'm looking at the instructions for how to install zsh completion [here](https://docs.bazel.build/versions/master/install.html#zsh) and am left a little confused about what to do. I'm only a casual user of ZSH, so I think I'm missing something fundamental.

># Getting zsh completion
>
>Bazel also comes with a zsh completion script. To install it:
>
>Add this script to a directory on your `$fpath`:
>```
>fpath[1,0]=~/.zsh/completion/
>mkdir -p ~/.zsh/completion/
>cp scripts/zsh_completion/_bazel ~/.zsh/completion
>```
>
>You may have to call `rm -f ~/.zcompdump; compinit` the first time to make it work.
>
>Optionally, add the following to your .zshrc.
>```
># This way the completion script does not have to parse Bazel's options
># repeatedly.  The directory in cache-path must be created manually.
>zstyle ':completion:*' use-cache on
>zstyle ':completion:*' cache-path ~/.zsh/cache
>```

The second step is very clear, but the first is confusing to me.

My `$fpath` includes a whole list of directories. So should I just pick a directory and write a file with the contents of that first script? Does it matter what I name it? Is there an existing convention I should be following? I'm reviewing the docs for zsh functions at http://zsh.sourceforge.net/Doc/Release/Functions.html, but I'm still unsure of how to proceed.

Issue comments:
I know nothing about zsh.

@schroederc : I believe you added the zsh completion script to Bazel in commit https://github.com/bazelbuild/bazel/commit/6b2766dd0, so I'm hoping you can help.
@damienmg : you approved Cody's change, you may know about zsh.
also confused by this sentence
The `_bazel` file just needs to be in one of the directories listed in your `fpath`.  The installation example shows how add a directory to your `fpath` and move the `_bazel` file into it, but if you already have a directory in your `fpath` that you prefer, you can move `_bazel` there instead.

It doesn't matter what the name of the directory is at all (`$HOME/.zsh/completion/` is just commonly used).  The `_bazel` filename only matters because that is what the completion function is named (i.e. https://github.com/bazelbuild/bazel/blob/64d9a4d6dcd720a3b7a60ff550a17a7707dd41d0/scripts/zsh_completion/_bazel#L247).  Otherwise, it's only a convention to name the completion file/function after the command it completes with a leading underscore.  When `compinit` is run, zsh will look through all files in all of the `fpath` directories and look for `#compdef` lines at the start of each to register completion functions.
Oh, I see. So the documentation was written from the perspective of that file and was copy/pasted/generated into documentation here: https://docs.bazel.build/versions/master/install.html#zsh

It looks like there may be a need to reword it.
The document disappeared. Is zsh auto completion not supported anymore?
Looking at the [history of install.md](https://github.com/bazelbuild/bazel/commits/master/site/docs/install.md), the instructions were there at [3e0c545404be6bce908d035044a5ff0ee41cc472](https://github.com/bazelbuild/bazel/blob/3e0c545404be6bce908d035044a5ff0ee41cc472/site/docs/install.md), but not anymore at [70e84f8926bd2cc38fea9e74af292d19038607b8](https://github.com/bazelbuild/bazel/blob/70e84f8926bd2cc38fea9e74af292d19038607b8/site/docs/install.md).

Let me see if they are still up-to-date and put them back.
FYI: alternatively, you guys may try this https://github.com/jackwish/bazel which is to make the process easier.
on macOS the zsh completions are installed automatically if you install via homebrew

Pull request review comments:

Patch that resolved the issue:
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 04b2fd401b1ea1..77410c6b11d506 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -47,6 +47,7 @@ <h3>Using Bazel</h3>
                    <li><a href="/versions/{{ site.version }}/install-os-x.html">Installing on macOS</a></li>
                    <li><a href="/versions/{{ site.version }}/install-windows.html">Installing on Windows</a></li>
                    <li><a href="/versions/{{ site.version }}/install-compile-source.html">Compiling from Source</a></li>
+                   <li><a href="/versions/{{ site.version }}/completion.html">Command-Line Completion</a></li>
                    <li><a href="/versions/{{ site.version }}/ide.html">Integrating with IDEs</a></li>
                  </ul>
                 </li>
diff --git a/site/docs/completion.md b/site/docs/completion.md
new file mode 100644
index 00000000000000..4936bf6aaa8713
--- /dev/null
+++ b/site/docs/completion.md
@@ -0,0 +1,90 @@
+---
+layout: documentation
+title: "Command-Line Completion"
+---
+
+# Command-Line Completion
+
+You can enable command-line completion (also known as tab-completion) in Bash
+and Zsh. This lets you tab-complete command names, flags names and flag values,
+and target names.
+
+<h2 id="bash">Bash completion</h2>
+
+Bazel comes with a Bash completion script.
+
+If you installed Bazel:
+
+*   From the APT repository, then you're done -- the Bash completion script is
+    already installed in `/etc/bash_completion.d`.
+
+*   From the installer downloaded from GitHub, then:
+    1.  Locate the absolute path of the completion file. The installer copied it
+        to the `bin` directory.  
+
+        Example: if you ran the installer with `--user`, this will be
+        `$HOME/.bazel/bin`. If you ran the installer as root, this will be
+        `/usr/local/bazel/bin`.
+    2.  Do one of the following:
+        *   Either copy this file to your completion directory (if you have
+            one).
+
+            Example: on Ubuntu this is the `/etc/bash_completion.d` directory.
+        *   Or source the completion file from Bash's RC file.
+
+            Add a line similar to the one below to your `~/.bashrc` (on Ubuntu)
+            or `~/.bash_profile` (on macOS), using the path to your completion
+            file's absolute path:
+
+            ```
+            source /path/to/bazel-complete.bash
+            ```
+
+*   Via [bootstrapping](install-compile-source.html), then:
+    1.  Build the completion script:
+
+        ```
+        bazel build //scripts:bazel-complete.bash
+        ```
+    2.  The completion file is built under
+        `bazel-bin/scripts/bazel-complete.bash`.
+
+        Do one of the following:
+        *   Either copy this file to your completion directory (if you have
+            one).
+
+            Example: on Ubuntu this is the `/etc/bash_completion.d` directory
+        *   Or copy it somewhere on your local disk, e.g. to `$HOME`, and
+            source the completion file from Bash's RC file.
+
+            Add a line similar to the one below to your `~/.bashrc` (on Ubuntu)
+            or `~/.bash_profile` (on macOS), using the path to your completion
+            file's absolute path:
+
+            ```
+            source /path/to/bazel-complete.bash
+            ```
+
+<h2 name="zsh">Zsh completion</h2>
+
+Bazel also comes with a Zsh completion script. To install it:
+
+1.  Add this script to a directory on your `$fpath`:
+
+    ```
+    fpath[1,0]=~/.zsh/completion/
+    mkdir -p ~/.zsh/completion/
+    cp scripts/zsh_completion/_bazel ~/.zsh/completion
+    ```
+
+    You may have to call `rm -f ~/.zcompdump; compinit`
+    the first time to make it work.
+
+2.  Optionally, add the following to your .zshrc.
+
+    ```
+    # This way the completion script does not have to parse Bazel's options
+    # repeatedly.  The directory in cache-path must be created manually.
+    zstyle ':completion:*' use-cache on
+    zstyle ':completion:*' cache-path ~/.zsh/cache
+    ```
diff --git a/site/docs/install-os-x.md b/site/docs/install-os-x.md
index eb8a5aced14465..77f2f7d4e5ab0e 100644
--- a/site/docs/install-os-x.md
+++ b/site/docs/install-os-x.md
@@ -13,8 +13,8 @@ Install Bazel on macOS using one of the following methods:
 
 Bazel comes with two completion scripts. After installing Bazel, you can:
 
-*   Access the [bash completion script](install.md)
-*   Install the [zsh completion script](install.md)
+*   Access the [bash completion script](completion.md#bash)
+*   Install the [zsh completion script](completion.md#zsh)
 
 ## <a name="install-with-installer-mac-os-x"></a>Installing using binary installer
 
diff --git a/site/docs/install-ubuntu.md b/site/docs/install-ubuntu.md
index ba36e6d3a4b6b3..a52ae8b39165ad 100644
--- a/site/docs/install-ubuntu.md
+++ b/site/docs/install-ubuntu.md
@@ -18,8 +18,8 @@ Install Bazel on Ubuntu using one of the following methods:
 
 Bazel comes with two completion scripts. After installing Bazel, you can:
 
-*   Access the [bash completion script](install.md)
-*   Install the [zsh completion script](install.md)
+*   Access the [bash completion script](completion.md#bash)
+*   Install the [zsh completion script](completion.md#zsh)
 
 ## <a name="install-with-installer-ubuntu"></a>Installing using binary installer
 


Test patch: