Merge pull request #1059 from masonj188/bash-docs

Improved auto-completion instructions and added example gifs
urfave · Feb 6, 2020 · 7a5ed48 · 7a5ed48
2 parents fed41d6 + 305e3de
commit 7a5ed48
Show file tree

Hide file tree

Showing 5 changed files with 117 additions and 13 deletions.
diff --git a/docs/v2/images/custom-bash-autocomplete.gif b/docs/v2/images/custom-bash-autocomplete.gif
diff --git a/docs/v2/images/custom-zsh-autocomplete.gif b/docs/v2/images/custom-zsh-autocomplete.gif
diff --git a/docs/v2/images/default-bash-autocomplete.gif b/docs/v2/images/default-bash-autocomplete.gif
diff --git a/docs/v2/images/default-zsh-autocomplete.gif b/docs/v2/images/default-zsh-autocomplete.gif
diff --git a/docs/v2/manual.md b/docs/v2/manual.md
@@ -995,10 +995,75 @@ have a single leading `-` or this will result in failures. For example,
 ### Bash Completion
 
 You can enable completion commands by setting the `EnableBashCompletion`
-flag on the `App` object.  By default, this setting will only auto-complete to
-show an app's subcommands, but you can write your own completion methods for
-the App or its subcommands.
+flag on the `App` object to `true`.  By default, this setting will allow auto-completion 
+for an app's subcommands, but you can write your own completion methods for
+the App or its subcommands as well.
 
+#### Default auto-completion
+
+```go
+package main
+import (
+	"fmt"
+	"log"
+	"os"
+	"github.com/urfave/cli"
+)
+func main() {
+	app := cli.NewApp()
+	app.EnableBashCompletion = true
+	app.Commands = []cli.Command{
+		{
+			Name:    "add",
+			Aliases: []string{"a"},
+			Usage:   "add a task to the list",
+			Action: func(c *cli.Context) error {
+				fmt.Println("added task: ", c.Args().First())
+				return nil
+			},
+		},
+		{
+			Name:    "complete",
+			Aliases: []string{"c"},
+			Usage:   "complete a task on the list",
+			Action: func(c *cli.Context) error {
+				fmt.Println("completed task: ", c.Args().First())
+				return nil
+			},
+		},
+		{
+			Name:    "template",
+			Aliases: []string{"t"},
+			Usage:   "options for task templates",
+			Subcommands: []cli.Command{
+				{
+					Name:  "add",
+					Usage: "add a new template",
+					Action: func(c *cli.Context) error {
+						fmt.Println("new task template: ", c.Args().First())
+						return nil
+					},
+				},
+				{
+					Name:  "remove",
+					Usage: "remove an existing template",
+					Action: func(c *cli.Context) error {
+						fmt.Println("removed task template: ", c.Args().First())
+						return nil
+					},
+				},
+			},
+		},
+	}
+	err := app.Run(os.Args)
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+```
+![](/docs/v2/images/default-bash-autocomplete.gif)
+
+#### Custom auto-completion
 <!-- {
   "args": ["complete", "&#45;&#45;generate&#45;bash&#45;completion"],
   "output": "laundry"
@@ -1047,30 +1112,52 @@ func main() {
   }
 }
 ```
+![](/docs/v2/images/custom-bash-autocomplete.gif)
 
 #### Enabling
 
-Source the `autocomplete/bash_autocomplete` file in your .bashrc file while setting the `PROG` variable to the name of your program:
+To enable auto-completion for the current shell session, a bash script,
+`autocomplete/bash_autocomplete` is included in this repo.
 
-```
-PROG=myprogram source /.../cli/autocomplete/bash_autocomplete
-```
+To use `autocomplete/bash_autocomplete` set an environment variable named `PROG` to 
+the name of your program and then `source` the `autocomplete/bash_autocomplete` file.
+
+For example, if your cli program is called `myprogram`:
 
-#### Distribution
+`PROG=myprogram source path/to/cli/autocomplete/bash_autocomplete`
+
+Auto-completion is now enabled for the current shell, but will not persist into a new shell.
+
+#### Distribution and Persistent Autocompletion
 
 Copy `autocomplete/bash_autocomplete` into `/etc/bash_completion.d/` and rename
 it to the name of the program you wish to add autocomplete support for (or
 automatically install it there if you are distributing a package). Don't forget
-to source the file to make it active in the current shell.
+to source the file or restart your shell to activate the auto-completion.
 
 ```
-sudo cp src/bash_autocomplete /etc/bash_completion.d/<myprogram>
+sudo cp path/to/autocomplete/bash_autocomplete /etc/bash_completion.d/<myprogram>
 source /etc/bash_completion.d/<myprogram>
 ```
 
-Alternatively, you can just document that users should source the generic
-`autocomplete/bash_autocomplete` in their bash configuration with `$PROG` set
-to the name of their program (as above).
+Alternatively, you can just document that users should `source` the generic
+`autocomplete/bash_autocomplete` and set `$PROG` within their bash configuration 
+file, adding these lines:
+
+```
+PROG=<myprogram>
+source path/to/cli/autocomplete/bash_autocomplete
+```
+Keep in mind that if they are enabling auto-completion for more than one program, 
+they will need to set `PROG` and source `autocomplete/bash_autocomplete` for each 
+program, like so:
+
+```
+PROG=<program1>
+source path/to/cli/autocomplete/bash_autocomplete
+PROG=<program2>
+source path/to/cli/autocomplete/bash_autocomplete
+```
 
 #### Customization
 
@@ -1107,6 +1194,23 @@ func main() {
 }
 ```
 
+#### ZSH Support
+Auto-completion for ZSH is also supported using the `autocomplete/zsh_autocomplete` 
+file included in this repo. Two environment variables are used, `PROG` and `_CLI_ZSH_AUTOCOMPLETE_HACK`. 
+Set `PROG` to the program name as before, set `_CLI_ZSH_AUTOCOMPLETE_HACK` to `1`, and 
+then `source path/to/autocomplete/zsh_autocomplete`. Adding the following lines to your ZSH 
+configuration file (usually `.zshrc`) will allow the auto-completion to persist across new shells:
+
+```
+PROG=<myprogram>
+_CLI_ZSH_AUTOCOMPLETE_HACK=1
+source  path/to/autocomplete/zsh_autocomplete
+```
+#### ZSH default auto-complete example
+![](/docs/v2/images/default-zsh-autocomplete.gif)
+#### ZSH custom auto-complete example
+![](/docs/v2/images/custom-zsh-autocomplete.gif)
+
 ### Generated Help Text
 
 The default help flag (`-h/--help`) is defined as `cli.HelpFlag` and is checked