From 35e3e17f72c0c9099e6ac20a59e85e4de9b74c93 Mon Sep 17 00:00:00 2001
From: Bruno Michel <bmichel@menfin.info>
Date: Mon, 23 Oct 2023 11:16:37 +0200
Subject: [PATCH] Improve help for shell completion

---
 cmd/completion.go                 | 35 +++++++++++++++++++++++++++---
 docs/cli/cozy-stack_completion.md | 36 +++++++++++++++++++++++++------
 2 files changed, 62 insertions(+), 9 deletions(-)

diff --git a/cmd/completion.go b/cmd/completion.go
index 35c71f05387..de370094d3c 100644
--- a/cmd/completion.go
+++ b/cmd/completion.go
@@ -13,7 +13,17 @@ var completionCmd = &cobra.Command{
 	Long: `
 Output shell completion code for the specified shell (bash, zsh, or fish). The
 shell code must be evalutated to provide interactive completion of cozy-stack
-commands.  This can be done by sourcing it from the .bash_profile.
+commands.
+
+Bash:
+
+  $ source <(cozy-stack completion bash)
+
+  # To load completions for each session, execute once:
+  # Linux:
+  $ cozy-stack completion bash > /etc/bash_completion.d/cozy-stack
+  # macOS:
+  $ cozy-stack completion bash > $(brew --prefix)/etc/bash_completion.d/cozy-stack
 
 Note: this requires the bash-completion framework, which is not installed by
 default on Mac.  This can be installed by using homebrew:
@@ -23,8 +33,27 @@ default on Mac.  This can be installed by using homebrew:
 Once installed, bash_completion must be evaluated.  This can be done by adding the
 following line to the .bash_profile
 
-    $ source $(brew --prefix)/etc/bash_completion`,
-	Example:   `# cozy-stack completion bash > /etc/bash_completion.d/cozy-stack`,
+    $ source $(brew --prefix)/etc/bash_completion
+
+Zsh:
+
+  # If shell completion is not already enabled in your environment,
+  # you will need to enable it.  You can execute the following once:
+
+  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+  # To load completions for each session, execute once:
+  $ cozy-stack completion zsh > "${fpath[1]}/_cozy-stack"
+
+  # You will need to start a new shell for this setup to take effect.
+
+fish:
+
+  $ cozy-stack completion fish | source
+
+  # To load completions for each session, execute once:
+  $ cozy-stack completion fish > /etc/fish/completions/cozy-stack.fish
+`,
 	ValidArgs: []string{"bash", "zsh", "fish"},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 1 {
diff --git a/docs/cli/cozy-stack_completion.md b/docs/cli/cozy-stack_completion.md
index 73b0ef4cede..1053cf7cce5 100644
--- a/docs/cli/cozy-stack_completion.md
+++ b/docs/cli/cozy-stack_completion.md
@@ -7,7 +7,17 @@ Output shell completion code for the specified shell
 
 Output shell completion code for the specified shell (bash, zsh, or fish). The
 shell code must be evalutated to provide interactive completion of cozy-stack
-commands.  This can be done by sourcing it from the .bash_profile.
+commands.
+
+Bash:
+
+  $ source <(cozy-stack completion bash)
+
+  # To load completions for each session, execute once:
+  # Linux:
+  $ cozy-stack completion bash > /etc/bash_completion.d/cozy-stack
+  # macOS:
+  $ cozy-stack completion bash > $(brew --prefix)/etc/bash_completion.d/cozy-stack
 
 Note: this requires the bash-completion framework, which is not installed by
 default on Mac.  This can be installed by using homebrew:
@@ -19,14 +29,28 @@ following line to the .bash_profile
 
     $ source $(brew --prefix)/etc/bash_completion
 
-```
-cozy-stack completion <shell> [flags]
-```
+Zsh:
+
+  # If shell completion is not already enabled in your environment,
+  # you will need to enable it.  You can execute the following once:
+
+  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+  # To load completions for each session, execute once:
+  $ cozy-stack completion zsh > "${fpath[1]}/_cozy-stack"
+
+  # You will need to start a new shell for this setup to take effect.
+
+fish:
+
+  $ cozy-stack completion fish | source
+
+  # To load completions for each session, execute once:
+  $ cozy-stack completion fish > /etc/fish/completions/cozy-stack.fish
 
-### Examples
 
 ```
-# cozy-stack completion bash > /etc/bash_completion.d/cozy-stack
+cozy-stack completion <shell> [flags]
 ```
 
 ### Options