fix: shell completions

- disables default `completion` cobra sub-command
- adds a `--completion [bash|zsh|fish]` flag which will generate shell completions using cobra's built-in support
- adds `installShellCompletion` to the `treefmt` package (this will need added to the nixpkgs entry after release)

The completions are static and address the first half of #529.

Signed-off-by: Brian McGee <[email protected]>

Author: brianmcgee

cmd/completions.go

@@ -0,0 +1,29 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+func generateShellCompletions(cmd *cobra.Command, args []string) error {
+	var err error
+
+	switch args[0] {
+	case "bash":
+		err = cmd.Root().GenBashCompletion(os.Stdout)
+	case "zsh":
+		err = cmd.Root().GenZshCompletion(os.Stdout)
+	case "fish":
+		err = cmd.Root().GenFishCompletion(os.Stdout, true)
+	default:
+		err = fmt.Errorf("unsupported shell: %s", args[0])
+	}
+
+	if err != nil {
+		err = fmt.Errorf("failed to generate shell completions: %w", err)
+	}
+
+	return err
+}

cmd/root.go

@@ -16,11 +16,6 @@ import (
 )
 
 func NewRoot() (*cobra.Command, *stats.Stats) {
-	var (
-		treefmtInit bool
-		configFile  string
-	)
-
 	// create a viper instance for reading in config
 	v, err := config.NewViper()
 	if err != nil {
@@ -35,6 +30,9 @@ func NewRoot() (*cobra.Command, *stats.Stats) {
 		Use:     build.Name + " <paths...>",
 		Short:   "The formatter multiplexer",
 		Version: build.Version,
+		CompletionOptions: cobra.CompletionOptions{
+			DisableDefaultCmd: true,
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runE(v, &statz, cmd, args)
 		},
@@ -53,17 +51,25 @@ func NewRoot() (*cobra.Command, *stats.Stats) {
 
 	cmd.HelpTemplate()
 
-	// add a couple of special flags which don't have a corresponding entry in treefmt.toml
-	fs.StringVar(
-		&configFile, "config-file", "",
+	// add a config file flag and some others for special subcommands
+	fs.String(
+		"config-file", "",
 		"Load the config file from the given path (defaults to searching upwards for treefmt.toml or "+
 			".treefmt.toml).",
 	)
-	fs.BoolVarP(
-		&treefmtInit, "init", "i", false,
+
+	// add a flag for the init sub command
+	fs.BoolP(
+		"init", "i", false,
 		"Create a treefmt.toml file in the current directory.",
 	)
 
+	// add a flag for generating shell completions
+	fs.String(
+		"completion", "",
+		"[bash|zsh|fish] Generate shell completion scripts for the specified shell.",
+	)
+
 	// bind our command's flags to viper
 	if err := v.BindPFlags(fs); err != nil {
 		cobra.CheckErr(fmt.Errorf("failed to bind global config to viper: %w", err))
@@ -91,9 +97,19 @@ func runE(v *viper.Viper, statz *stats.Stats, cmd *cobra.Command, args []string)
 	if init, err := flags.GetBool("init"); err != nil {
 		return fmt.Errorf("failed to read init flag: %w", err)
 	} else if init {
-		err := _init.Run()
-		if err != nil {
-			return fmt.Errorf("failed to run init command: %w", err)
+		if initErr := _init.Run(); initErr != nil {
+			return fmt.Errorf("failed to run init command: %w", initErr)
+		}
+
+		return nil
+	}
+
+	// check if we are running the completion command
+	if shell, err := flags.GetString("completion"); err != nil {
+		return fmt.Errorf("failed to read completion flag: %w", err)
+	} else if shell != "" {
+		if completionsErr := generateShellCompletions(cmd, []string{shell}); completionsErr != nil {
+			return fmt.Errorf("failed to generate shell completions: %w", completionsErr)
 		}
 
 		return nil

docs/content/getting-started/usage.md

@@ -14,6 +14,7 @@ Flags:
       --allow-missing-formatter   Do not exit with error if a configured formatter is missing. (env $TREEFMT_ALLOW_MISSING_FORMATTER)
       --ci                        Runs treefmt in a CI mode, enabling --no-cache, --fail-on-change and adjusting some other settings best suited to a CI use case. (env $TREEFMT_CI)
   -c, --clear-cache               Reset the evaluation cache. Use in case the cache is not precise enough. (env $TREEFMT_CLEAR_CACHE)
+      --completion string         [bash|zsh|fish] Generate shell completion scripts for the specified shell.
       --config-file string        Load the config file from the given path (defaults to searching upwards for treefmt.toml or .treefmt.toml).
       --cpu-profile string        The file into which a cpu profile will be written. (env $TREEFMT_CPU_PROFILE)
       --excludes strings          Exclude files or directories matching the specified globs. (env $TREEFMT_EXCLUDES)
@@ -126,6 +127,16 @@ in
   flake.defaultNix
 ```
 
+## Shell Completion
+
+To generate completions for your preferred shell:
+
+```console
+❯ treefmt --completion bash
+❯ treefmt --completion fish
+❯ treefmt --completion zsh
+```
+
 ## CI integration
 
 We recommend using the [CI option](./configure.md#ci) in continuous integration environments.

nix/packages/treefmt/default.nix

@@ -47,7 +47,10 @@ in
     ];
 
     nativeBuildInputs =
-      [pkgs.git]
+      (with pkgs; [
+        git
+        installShellFiles
+      ])
       ++
       # we need some formatters available for the tests
       import ./formatters.nix pkgs;
@@ -63,6 +66,15 @@ in
       git config --global user.name "Treefmt Test"
     '';
 
+    postInstall = ''
+      export HOME=$PWD
+
+      installShellCompletion --cmd treefmt \
+          --bash <($out/bin/treefmt --completion bash) \
+          --fish <($out/bin/treefmt --completion fish) \
+          --zsh <($out/bin/treefmt --completion zsh)
+    '';
+
     passthru = let
       inherit (perSystem.self) treefmt;
     in {