env: hidden - extend config to skip _carapace command

defaultActions.go

@@ -539,12 +539,19 @@ func ActionCommands(cmd *cobra.Command) Action {
 
 		batch := Batch()
 		for _, subcommand := range cmd.Commands() {
-			if (!subcommand.Hidden || env.Hidden()) && subcommand.Deprecated == "" {
-				group := common.Group{Cmd: subcommand}
-				batch = append(batch, ActionStyledValuesDescribed(subcommand.Name(), subcommand.Short, group.Style()).Tag(group.Tag()))
-				for _, alias := range subcommand.Aliases {
-					batch = append(batch, ActionStyledValuesDescribed(alias, subcommand.Short, group.Style()).Tag(group.Tag()))
-				}
+			switch {
+			case subcommand.Hidden && subcommand.Name() == "_carapace" && env.Hidden() != env.HIDDEN_INCLUDE_CARAPACE:
+				continue // skip `_carapace` subcommand
+			case subcommand.Hidden && env.Hidden() == env.HIDDEN_NONE:
+				continue // skip all hidden commands
+			case subcommand.Deprecated != "":
+				continue // skip deprecated commands
+			}
+
+			group := common.Group{Cmd: subcommand}
+			batch = append(batch, ActionStyledValuesDescribed(subcommand.Name(), subcommand.Short, group.Style()).Tag(group.Tag()))
+			for _, alias := range subcommand.Aliases {
+				batch = append(batch, ActionStyledValuesDescribed(alias, subcommand.Short, group.Style()).Tag(group.Tag()))
 			}
 		}
 		return batch.ToA().UidF(func(s string, uc uid.Context) (*url.URL, error) {

example/cmd/subcommand_test.go

@@ -0,0 +1,53 @@
+package cmd
+
+import (
+	"testing"
+
+	"github.com/carapace-sh/carapace"
+	"github.com/carapace-sh/carapace/pkg/sandbox"
+)
+
+func TestSubcommand(t *testing.T) {
+	sandbox.Package(t, "github.com/carapace-sh/carapace/example")(func(s *sandbox.Sandbox) {
+		s.Run("subcommand", "").
+			Expect(carapace.Batch(
+				carapace.ActionValuesDescribed(
+					"a1", "subcommand with alias",
+					"a2", "subcommand with alias",
+					"alias", "subcommand with alias",
+				).Tag("other commands"),
+				carapace.ActionValuesDescribed(
+					"group", "subcommand with group",
+				).Tag("group commands").Style("blue"),
+			).ToA())
+
+		s.Env("CARAPACE_HIDDEN", "1")
+		s.Run("subcommand", "").
+			Expect(carapace.Batch(
+				carapace.ActionValuesDescribed(
+					"a1", "subcommand with alias",
+					"a2", "subcommand with alias",
+					"alias", "subcommand with alias",
+					"hidden", "hidden subcommand",
+				).Tag("other commands"),
+				carapace.ActionValuesDescribed(
+					"group", "subcommand with group",
+				).Tag("group commands").Style("blue"),
+			).ToA())
+
+		s.Env("CARAPACE_HIDDEN", "2")
+		s.Run("subcommand", "").
+			Expect(carapace.Batch(
+				carapace.ActionValuesDescribed(
+					"a1", "subcommand with alias",
+					"a2", "subcommand with alias",
+					"alias", "subcommand with alias",
+					"hidden", "hidden subcommand",
+					"_carapace", "",
+				).Tag("other commands"),
+				carapace.ActionValuesDescribed(
+					"group", "subcommand with group",
+				).Tag("group commands").Style("blue"),
+			).ToA())
+	})
+}

internal/env/env.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"errors"
 	"os"
+	"strconv"
 	"strings"
 
 	"github.com/carapace-sh/carapace/internal/common"
@@ -57,8 +58,23 @@ func Log() bool {
 	return getBool(CARAPACE_LOG)
 }
 
-func Hidden() bool {
-	return getBool(CARAPACE_HIDDEN)
+type hidden int
+
+const (
+	HIDDEN_NONE hidden = iota
+	HIDDEN_EXCLUDE_CARAPACE
+	HIDDEN_INCLUDE_CARAPACE
+)
+
+func Hidden() hidden {
+	switch parsed, _ := strconv.Atoi(os.Getenv(CARAPACE_HIDDEN)); parsed {
+	case 1:
+		return HIDDEN_EXCLUDE_CARAPACE
+	case 2:
+		return HIDDEN_INCLUDE_CARAPACE
+	default: // 0 or error
+		return HIDDEN_NONE
+	}
 }
 
 func CoverDir() string {

internalActions.go

@@ -94,7 +94,7 @@ func actionFlags(cmd *cobra.Command) Action {
 		batch := Batch()
 		flagSet.VisitAll(func(f *pflagfork.Flag) {
 			switch {
-			case f.Hidden && !env.Hidden():
+			case f.Hidden && env.Hidden() == env.HIDDEN_NONE:
 				return // skip hidden flags
 			case f.Deprecated != "":
 				return // skip deprecated flags