[GH-1505] add documentation regarding autocompletion for velero CLI (#…

…2208)

* add documentation regarding autocompletion for velero CLI

Signed-off-by: Carlos Panato <ctadeu@gmail.com>

site/docs/master/basic-install.md

@@ -51,8 +51,13 @@ Velero uses storage provider plugins to integrate with a variety of storage syst
 
 _Note: if your object storage provider is different than your volume snapshot provider, follow the installation instructions for your object storage provider first, then return here and follow the instructions to [add your volume snapshot provider][4]._
 
+## Command line Autocompletion
+
+Please refer to [this part of the documentation][5].
+
 [0]: supported-providers.md
 [1]: https://github.com/vmware-tanzu/velero/releases/latest
 [2]: on-premises.md
 [3]: overview-plugins.md
 [4]: customize-installation.md#install-an-additional-volume-snapshot-provider
+[5]: customize-installation.md#optional-velero-cli-configurations

site/docs/master/customize-installation.md

@@ -11,6 +11,7 @@
   - [Install an additional volume snapshot provider](#install-an-additional-volume-snapshot-provider)
   - [Generate YAML only](#generate-yaml-only)
   - [Additional options](#additional-options)
+  - [Optional Velero CLI configurations](#optional-velero-cli-configurations)
 
 ## Plugins
 
@@ -30,7 +31,7 @@ If you are using an alternate identity mechanism, such as kube2iam/kiam on AWS,
 
 By default, `velero install` does not install Velero's [restic integration][3]. To enable it, specify the `--use-restic` flag. 
 
-If you've already run `velero install` without the `--use-restic` flag, you can run the same command again, including the `--use-restic` flag, to add the restic integration to your existing install. 
+If you've already run `velero install` without the `--use-restic` flag, you can run the same command again, including the `--use-restic` flag, to add the restic integration to your existing install.
 
 ## Customize resource requests and limits
 
@@ -89,6 +90,148 @@ If you are installing Velero in Kubernetes 1.13.x or earlier, you need to use `k
 
 Run `velero install --help` or see the [Helm chart documentation](https://github.com/helm/charts/tree/master/stable/velero) for the full set of installation options.
 
+## Optional Velero CLI configurations
+
+### Enabling shell autocompletion
+
+**Velero CLI** provides autocompletion support for `Bash` and `Zsh`, which can save you a lot of typing.
+
+Below are the procedures to set up autocompletion for `Bash` (including the difference between `Linux` and `macOS`) and `Zsh`.
+
+## Bash on Linux
+
+The **Velero CLI** completion script for `Bash` can be generated with the command `velero completion bash`. Sourcing the completion script in your shell enables velero autocompletion.
+
+However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
+
+### Install bash-completion
+
+`bash-completion` is provided by many package managers (see [here](https://github.com/scop/bash-completion#installation)). You can install it with `apt-get install bash-completion` or `yum install bash-completion`, etc.
+
+The above commands create `/usr/share/bash-completion/bash_completion`, which is the main script of bash-completion. Depending on your package manager, you have to manually source this file in your `~/.bashrc` file.
+
+To find out, reload your shell and run `type _init_completion`. If the command succeeds, you're already set, otherwise add the following to your `~/.bashrc` file:
+
+```shell
+source /usr/share/bash-completion/bash_completion
+```
+
+Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
+
+### Enable Velero CLI autocompletion for Bash on Linux
+
+You now need to ensure that the **Velero CLI** completion script gets sourced in all your shell sessions. There are two ways in which you can do this:
+
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(velero completion bash)' >>~/.bashrc
+    ```
+
+- Add the completion script to the `/etc/bash_completion.d` directory:
+
+    ```shell
+    velero completion bash >/etc/bash_completion.d/velero
+    ```
+
+- If you have an alias for velero, you can extend shell completion to work with that alias:
+
+    ```shell
+    echo 'alias v=velero' >>~/.bashrc
+    echo 'complete -F __start_velero v' >>~/.bashrc
+    ```
+
+> `bash-completion` sources all completion scripts in `/etc/bash_completion.d`.
+
+Both approaches are equivalent. After reloading your shell, velero autocompletion should be working.
+
+## Bash on macOS
+
+The **Velero CLI** completion script for Bash can be generated with `velero completion bash`. Sourcing this script in your shell enables velero completion.
+
+However, the velero completion script depends on [**bash-completion**](https://github.com/scop/bash-completion) which you thus have to previously install.
+
+
+> There are two versions of bash-completion, v1 and v2. V1 is for Bash 3.2 (which is the default on macOS), and v2 is for Bash 4.1+. The velero completion script **doesn't work** correctly with bash-completion v1 and Bash 3.2. It requires **bash-completion v2** and **Bash 4.1+**. Thus, to be able to correctly use velero completion on macOS, you have to install and use Bash 4.1+ ([*instructions*](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The following instructions assume that you use Bash 4.1+ (that is, any Bash version of 4.1 or newer).
+
+
+### Install bash-completion
+
+> As mentioned, these instructions assume you use Bash 4.1+, which means you will install bash-completion v2 (in contrast to Bash 3.2 and bash-completion v1, in which case kubectl completion won't work).
+
+You can test if you have bash-completion v2 already installed with `type _init_completion`. If not, you can install it with Homebrew:
+
+  ```shell
+  brew install bash-completion@2
+  ```
+
+As stated in the output of this command, add the following to your `~/.bashrc` file:
+
+  ```shell
+  export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
+  [[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
+  ```
+
+Reload your shell and verify that bash-completion v2 is correctly installed with `type _init_completion`.
+
+### Enable Velero CLI autocompletion for Bash on macOS
+
+You now have to ensure that the velero completion script gets sourced in all your shell sessions. There are multiple ways to achieve this:
+
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(velero completion bash)' >>~/.bashrc
+
+    ```
+
+- Add the completion script to the `/usr/local/etc/bash_completion.d` directory:
+
+    ```shell
+    velero completion bash >/usr/local/etc/bash_completion.d/velero
+    ```
+
+- If you have an alias for velero, you can extend shell completion to work with that alias:
+
+    ```shell
+    echo 'alias v=velero' >>~/.bashrc
+    echo 'complete -F __start_velero v' >>~/.bashrc
+    ```
+
+- If you installed velero with Homebrew (as explained [above](#install-with-homebrew-on-macos)), then the velero completion script should already be in `/usr/local/etc/bash_completion.d/velero`. In that case, you don't need to do anything.
+
+> The Homebrew installation of bash-completion v2 sources all the files in the `BASH_COMPLETION_COMPAT_DIR` directory, that's why the latter two methods work.
+
+In any case, after reloading your shell, velero completion should be working.
+
+
+## Autocompletion on Zsh
+
+The velero completion script for Zsh can be generated with the command `velero completion zsh`. Sourcing the completion script in your shell enables velero autocompletion.
+
+To do so in all your shell sessions, add the following to your `~/.zshrc` file:
+
+  ```shell
+  source <(velero completion zsh)
+  ```
+
+If you have an alias for kubectl, you can extend shell completion to work with that alias:
+
+  ```shell
+  echo 'alias v=velero' >>~/.zshrc
+  echo 'complete -F __start_velero v' >>~/.zshrc
+  ```
+
+After reloading your shell, kubectl autocompletion should be working.
+
+If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file:
+
+  ```shell
+  autoload -Uz compinit
+  compinit
+  ```
+
+
 [1]: https://github.com/vmware-tanzu/velero/releases/latest
 [2]: namespace.md
 [3]: restic.md

site/docs/v1.2.0/basic-install.md

@@ -51,8 +51,13 @@ Velero uses storage provider plugins to integrate with a variety of storage syst
 
 _Note: if your object storage provider is different than your volume snapshot provider, follow the installation instructions for your object storage provider first, then return here and follow the instructions to [add your volume snapshot provider][4]._
 
+## Command line Autocompletion
+
+Please refer to [this part of the documentation][5].
+
 [0]: supported-providers.md
 [1]: https://github.com/vmware-tanzu/velero/releases/latest
 [2]: on-premises.md
 [3]: overview-plugins.md
 [4]: customize-installation.md#install-an-additional-volume-snapshot-provider
+[5]: customize-installation.md#optional-velero-cli-configurations

site/docs/v1.2.0/customize-installation.md

@@ -11,6 +11,8 @@
   - [Install an additional volume snapshot provider](#install-an-additional-volume-snapshot-provider)
   - [Generate YAML only](#generate-yaml-only)
   - [Additional options](#additional-options)
+  - [Optional Velero CLI configurations](#optional-velero-cli-configurations)
+
 
 ## Plugins
 
@@ -89,6 +91,147 @@ If you are installing Velero in Kubernetes 1.13.x or earlier, you need to use `k
 
 Run `velero install --help` or see the [Helm chart documentation](https://github.com/helm/charts/tree/master/stable/velero) for the full set of installation options.
 
+## Optional Velero CLI configurations
+
+### Enabling shell autocompletion
+
+**Velero CLI** provides autocompletion support for `Bash` and `Zsh`, which can save you a lot of typing.
+
+Below are the procedures to set up autocompletion for `Bash` (including the difference between `Linux` and `macOS`) and `Zsh`.
+
+## Bash on Linux
+
+The **Velero CLI** completion script for `Bash` can be generated with the command `velero completion bash`. Sourcing the completion script in your shell enables velero autocompletion.
+
+However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
+
+### Install bash-completion
+
+`bash-completion` is provided by many package managers (see [here](https://github.com/scop/bash-completion#installation)). You can install it with `apt-get install bash-completion` or `yum install bash-completion`, etc.
+
+The above commands create `/usr/share/bash-completion/bash_completion`, which is the main script of bash-completion. Depending on your package manager, you have to manually source this file in your `~/.bashrc` file.
+
+To find out, reload your shell and run `type _init_completion`. If the command succeeds, you're already set, otherwise add the following to your `~/.bashrc` file:
+
+```shell
+source /usr/share/bash-completion/bash_completion
+```
+
+Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
+
+### Enable Velero CLI autocompletion for Bash on Linux
+
+You now need to ensure that the **Velero CLI** completion script gets sourced in all your shell sessions. There are two ways in which you can do this:
+
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(velero completion bash)' >>~/.bashrc
+    ```
+
+- Add the completion script to the `/etc/bash_completion.d` directory:
+
+    ```shell
+    velero completion bash >/etc/bash_completion.d/velero
+    ```
+
+- If you have an alias for velero, you can extend shell completion to work with that alias:
+
+    ```shell
+    echo 'alias v=velero' >>~/.bashrc
+    echo 'complete -F __start_velero v' >>~/.bashrc
+    ```
+
+> `bash-completion` sources all completion scripts in `/etc/bash_completion.d`.
+
+Both approaches are equivalent. After reloading your shell, velero autocompletion should be working.
+
+## Bash on macOS
+
+The **Velero CLI** completion script for Bash can be generated with `velero completion bash`. Sourcing this script in your shell enables velero completion.
+
+However, the velero completion script depends on [**bash-completion**](https://github.com/scop/bash-completion) which you thus have to previously install.
+
+
+> There are two versions of bash-completion, v1 and v2. V1 is for Bash 3.2 (which is the default on macOS), and v2 is for Bash 4.1+. The velero completion script **doesn't work** correctly with bash-completion v1 and Bash 3.2. It requires **bash-completion v2** and **Bash 4.1+**. Thus, to be able to correctly use velero completion on macOS, you have to install and use Bash 4.1+ ([*instructions*](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The following instructions assume that you use Bash 4.1+ (that is, any Bash version of 4.1 or newer).
+
+
+### Install bash-completion
+
+> As mentioned, these instructions assume you use Bash 4.1+, which means you will install bash-completion v2 (in contrast to Bash 3.2 and bash-completion v1, in which case kubectl completion won't work).
+
+You can test if you have bash-completion v2 already installed with `type _init_completion`. If not, you can install it with Homebrew:
+
+  ```shell
+  brew install bash-completion@2
+  ```
+
+As stated in the output of this command, add the following to your `~/.bashrc` file:
+
+  ```shell
+  export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"
+  [[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"
+  ```
+
+Reload your shell and verify that bash-completion v2 is correctly installed with `type _init_completion`.
+
+### Enable Velero CLI autocompletion for Bash on macOS
+
+You now have to ensure that the velero completion script gets sourced in all your shell sessions. There are multiple ways to achieve this:
+
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(velero completion bash)' >>~/.bashrc
+
+    ```
+
+- Add the completion script to the `/usr/local/etc/bash_completion.d` directory:
+
+    ```shell
+    velero completion bash >/usr/local/etc/bash_completion.d/velero
+    ```
+
+- If you have an alias for velero, you can extend shell completion to work with that alias:
+
+    ```shell
+    echo 'alias v=velero' >>~/.bashrc
+    echo 'complete -F __start_velero v' >>~/.bashrc
+    ```
+
+- If you installed velero with Homebrew (as explained [above](#install-with-homebrew-on-macos)), then the velero completion script should already be in `/usr/local/etc/bash_completion.d/velero`. In that case, you don't need to do anything.
+
+> The Homebrew installation of bash-completion v2 sources all the files in the `BASH_COMPLETION_COMPAT_DIR` directory, that's why the latter two methods work.
+
+In any case, after reloading your shell, velero completion should be working.
+
+
+## Autocompletion on Zsh
+
+The velero completion script for Zsh can be generated with the command `velero completion zsh`. Sourcing the completion script in your shell enables velero autocompletion.
+
+To do so in all your shell sessions, add the following to your `~/.zshrc` file:
+
+  ```shell
+  source <(velero completion zsh)
+  ```
+
+If you have an alias for kubectl, you can extend shell completion to work with that alias:
+
+  ```shell
+  echo 'alias v=velero' >>~/.zshrc
+  echo 'complete -F __start_velero v' >>~/.zshrc
+  ```
+
+After reloading your shell, kubectl autocompletion should be working.
+
+If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file:
+
+  ```shell
+  autoload -Uz compinit
+  compinit
+  ```
+
 [0]: supported-providers.md
 [1]: https://github.com/vmware-tanzu/velero/releases/latest
 [2]: namespace.md