feat: completion command (#1157)

cmd/task/task.go

@@ -83,6 +83,15 @@ func run() error {
 		return nil
 	}
 
+	if flags.Completion != "" {
+		script, err := task.Completion(flags.Completion)
+		if err != nil {
+			return err
+		}
+		fmt.Println(script)
+		return nil
+	}
+
 	if flags.Global {
 		home, err := os.UserHomeDir()
 		if err != nil {

completion.go

@@ -0,0 +1,34 @@
+package task
+
+import (
+	_ "embed"
+	"fmt"
+)
+
+//go:embed completion/bash/task.bash
+var completionBash string
+
+//go:embed completion/fish/task.fish
+var completionFish string
+
+//go:embed completion/ps/task.ps1
+var completionPowershell string
+
+//go:embed completion/zsh/_task
+var completionZsh string
+
+func Completion(completion string) (string, error) {
+	// Get the file extension for the selected shell
+	switch completion {
+	case "bash":
+		return completionBash, nil
+	case "fish":
+		return completionFish, nil
+	case "powershell":
+		return completionPowershell, nil
+	case "zsh":
+		return completionZsh, nil
+	default:
+		return "", fmt.Errorf("unknown shell: %s", completion)
+	}
+}

internal/flags/flags.go

@@ -38,6 +38,7 @@ var (
 	Version     bool
 	Help        bool
 	Init        bool
+	Completion  string
 	List        bool
 	ListAll     bool
 	ListJson    bool
@@ -80,6 +81,7 @@ func init() {
 	pflag.BoolVar(&Version, "version", false, "Show Task version.")
 	pflag.BoolVarP(&Help, "help", "h", false, "Shows Task usage.")
 	pflag.BoolVarP(&Init, "init", "i", false, "Creates a new Taskfile.yml in the current folder.")
+	pflag.StringVar(&Completion, "completion", "", "Generates shell completion script.")
 	pflag.BoolVarP(&List, "list", "l", false, "Lists tasks with description of current Taskfile.")
 	pflag.BoolVarP(&ListAll, "list-all", "a", false, "Lists tasks with or without a description.")
 	pflag.BoolVarP(&ListJson, "json", "j", false, "Formats task list as JSON.")

website/docs/deprecations/completion_scripts.mdx

@@ -0,0 +1,25 @@
+---
+slug: /deprecations/completion-scripts/
+---
+
+# Completion Scripts
+
+:::warning
+
+This deprecation breaks the following functionality:
+
+- Any direct references to the completion scripts in the Task git repository
+
+:::
+
+Direct use of the completion scripts in the `completion/*` directory of the
+[github.com/go-task/task][task] Git repository is deprecated. Any shell
+configuration that directly refers to these scripts will potentially break in
+the future as the scripts may be moved or deleted entirely. Any configuration
+should be updated to use the [new method for generating shell
+completions][completions] instead.
+
+{/* prettier-ignore-start */}
+[completions]: ../installation.mdx#setup-completions
+[task]: https://github.com/go-task/task
+{/* prettier-ignore-end */}

website/docs/installation.mdx

@@ -3,6 +3,9 @@ slug: /installation/
 sidebar_position: 2
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Installation
 
 Task offers many installation methods. Check out the available methods below.
@@ -247,65 +250,76 @@ released binary.
 
 ## Setup completions
 
-Download the autocompletion file corresponding to your shell.
+Some installation methods will automatically install completions too, but if
+this isn't working for you or your chosen method doesn't include them, you can
+run `task --completion <shell>` to output a completion script for any supported
+shell. There are a couple of ways these completions can be added to your shell
+config:
 
-[All completions are available on the Task repository](https://github.com/go-task/task/tree/main/completion).
+### Option 1. Load the completions in your shell's startup config (Recommended)
 
-### Bash
+This method loads the completion script from the currently installed version of
+task every time you create a new shell. This ensures that your completions are
+always up-to-date.
 
-First, ensure that you installed bash-completion using your package manager.
+<Tabs values={[ {label: 'bash', value: '1'}, {label: 'zsh', value: '2'},
+    {label: 'fish', value: '3'},
+    {label: 'powershell', value: '4'}
+  ]}>
 
-Make the completion file executable:
+<TabItem value="1">
+```shell title="~/.bashrc"
+eval "$(task --completion bash)"
+```
+</TabItem>
 
+<TabItem value="2">
+```shell title="~/.zshrc"
+eval "$(task --completion zsh)"
+```
+</TabItem>
+
+<TabItem value="3">
+```shell title="~/.config/fish/config.fish"
+task --completion fish | source
+```
+</TabItem>
+
+<TabItem value="4">
+```powershell title="$PROFILE\Microsoft.PowerShell_profile.ps1"
+Invoke-Expression (&task --completion powershell)
+```
+</TabItem></Tabs>
+
+### Option 2. Copy the script to your shell's completions directory
+
+This method requires you to manually update the completions whenever Task is
+updated. However, it is useful if you want to modify the completions yourself.
+
+<Tabs
+  values={[
+    {label: 'bash', value: '1'},
+    {label: 'zsh', value: '2'},
+    {label: 'fish', value: '3'}
+  ]}>
+
+<TabItem value="1">
 ```shell
-chmod +x path/to/task.bash
+task --completion bash > /etc/bash_completion.d/task
 ```
+</TabItem>
 
-After, add this to your `~/.bash_profile`:
+<TabItem value="2">
-
 ```shell
-source path/to/task.bash
+task --completion zsh  > /usr/local/share/zsh/site-functions/_task
 ```
+</TabItem>
 
-### ZSH
+<TabItem value="3">
-
-Put the `_task` file somewhere in your `$FPATH`:
-
 ```shell
-mv path/to/_task /usr/local/share/zsh/site-functions/_task
+task --completion fish > ~/.config/fish/completions/task.fish
-```
-
-Ensure that the following is present in your `~/.zshrc`:
-
-```shell
-autoload -U compinit
-compinit -i
-```
-
-ZSH version 5.7 or later is recommended.
-
-### Fish
-
-Move the `task.fish` completion script:
-
-```shell
-mv path/to/task.fish ~/.config/fish/completions/task.fish
-```
-
-### PowerShell
-
-Open your profile script with:
-
-```powershell
-mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue
-notepad $profile
-```
-
-Add the line and save the file:
-
-```shell
-Invoke-Expression -Command path/to/task.ps1
 ```
+</TabItem></Tabs>
 
 {/* prettier-ignore-start */}
 [go]: https://golang.org/