From ff661c3831e06a4b22a76f522f4dacdce3cf1361 Mon Sep 17 00:00:00 2001
From: rsteube <rsteube@users.noreply.github.com>
Date: Thu, 26 Jun 2025 18:16:00 +0200
Subject: [PATCH] env: hidden - extend config to skip `_carapace` command

---
 defaultActions.go              | 19 ++++++++----
 example/cmd/subcommand_test.go | 53 ++++++++++++++++++++++++++++++++++
 internal/env/env.go            | 20 +++++++++++--
 internalActions.go             |  2 +-
 4 files changed, 85 insertions(+), 9 deletions(-)
 create mode 100644 example/cmd/subcommand_test.go

diff --git a/defaultActions.go b/defaultActions.go
index 28cb69bfe..1a0b9a452 100644
--- a/defaultActions.go
+++ b/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) {
diff --git a/example/cmd/subcommand_test.go b/example/cmd/subcommand_test.go
new file mode 100644
index 000000000..49014d830
--- /dev/null
+++ b/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())
+	})
+}
diff --git a/internal/env/env.go b/internal/env/env.go
index d6f156324..5349ef8d6 100644
--- a/internal/env/env.go
+++ b/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 {
diff --git a/internalActions.go b/internalActions.go
index c1191e344..a36c0a741 100644
--- a/internalActions.go
+++ b/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