feat(list): add --tree flag for namespace-grouped task display

Introduces --tree (-T), which renders tasks grouped by their top-level
namespace with indentation instead of a flat list. Namespaced groups
appear first, followed by a separator and root-level tasks.

Refs: #2091

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: trevor-vaughan

cmd/task/task.go

@@ -146,6 +146,7 @@ func run() error {
 		flags.NoStatus,
 		flags.Nested,
 		flags.Long,
+		flags.Tree,
 	)
 	if listOptions.ShouldListTasks() {
 		if flags.Silent {

formatter_test.go

@@ -262,6 +262,35 @@ func TestListLong(t *testing.T) {
 	)
 }
 
+func TestListTree(t *testing.T) {
+	t.Parallel()
+
+	NewFormatterTest(t,
+		WithExecutorOptions(
+			task.WithDir("testdata/list_tree"),
+		),
+		WithListOptions(task.ListOptions{
+			ListOnlyTasksWithDescriptions: true,
+			Tree:                          true,
+		}),
+	)
+}
+
+func TestListTreeLong(t *testing.T) {
+	t.Parallel()
+
+	NewFormatterTest(t,
+		WithExecutorOptions(
+			task.WithDir("testdata/list_tree_long"),
+		),
+		WithListOptions(task.ListOptions{
+			ListOnlyTasksWithDescriptions: true,
+			Tree:                          true,
+			Long:                          true,
+		}),
+	)
+}
+
 func TestJsonListLong(t *testing.T) {
 	t.Parallel()
 

help.go

@@ -27,17 +27,19 @@ type ListOptions struct {
 	NoStatus                      bool
 	Nested                        bool
 	Long                          bool
+	Tree                          bool
 }
 
 // NewListOptions creates a new ListOptions instance
-func NewListOptions(list, listAll, listAsJson, noStatus, nested, long bool) ListOptions {
+func NewListOptions(list, listAll, listAsJson, noStatus, nested, long, tree bool) ListOptions {
 	return ListOptions{
 		ListOnlyTasksWithDescriptions: list,
 		ListAllTasks:                  listAll,
 		FormatTaskListAsJSON:          listAsJson,
 		NoStatus:                      noStatus,
 		Nested:                        nested,
 		Long:                          long,
+		Tree:                          tree,
 	}
 }
 
@@ -89,6 +91,9 @@ func (e *Executor) ListTasks(o ListOptions) (bool, error) {
 		}
 		return false, nil
 	}
+	if o.Tree {
+		return e.listTasksTree(tasks, o)
+	}
 	e.Logger.Outf(logger.Default, "task: Available tasks for this project:\n")
 
 	// Format in tab-separated columns with a tab stop of 8.
@@ -162,6 +167,63 @@ func (e *Executor) ListTaskNames(allTasks bool) error {
 	return nil
 }
 
+func (e *Executor) listTasksTree(tasks []*ast.Task, o ListOptions) (bool, error) {
+	e.Logger.Outf(logger.Default, "task: Available tasks for this project:\n")
+
+	groups := listing.GroupByNamespace(tasks)
+	hasNamespaced := listing.HasNamespacedGroups(groups)
+	hasRoot := listing.HasRootGroup(groups)
+	showSeparator := hasNamespaced && hasRoot
+
+	// Move root group to end so namespaced groups appear first
+	if showSeparator {
+		for i, g := range groups {
+			if g.Namespace == "" && i < len(groups)-1 {
+				rootGroup := groups[i]
+				groups = append(groups[:i], groups[i+1:]...)
+				groups = append(groups, rootGroup)
+				break
+			}
+		}
+	}
+
+	w := tabwriter.NewWriter(e.Stdout, 0, 8, 6, ' ', 0)
+	firstGroup := true
+	for _, group := range groups {
+		isRoot := group.Namespace == ""
+		if !firstGroup {
+			_, _ = fmt.Fprint(w, "\n")
+		}
+		firstGroup = false
+		if isRoot && showSeparator {
+			e.Logger.FOutf(w, logger.Dim, "  ─────\n\n")
+		}
+		if !isRoot {
+			e.Logger.FOutf(w, logger.Dim, "  %s\n", group.Namespace)
+		}
+		for _, task := range group.Tasks {
+			name := group.LocalName(task)
+			desc := strings.ReplaceAll(task.Desc, "\n", " ")
+			indent := "  "
+			if !isRoot {
+				indent = "    "
+			}
+			nameColor := logger.Green
+			if task.Internal {
+				nameColor = logger.Dim
+			}
+			e.Logger.FOutf(w, nameColor, "%s%s", indent, name)
+			e.Logger.FOutf(w, logger.Default, ":\t%s", desc)
+			if len(task.Aliases) > 0 {
+				e.Logger.FOutf(w, logger.Cyan, "\t(aliases: %s)", strings.Join(task.Aliases, ", "))
+			}
+			_, _ = fmt.Fprint(w, "\n")
+			e.writeTaskDetails(w, task, indent+"  \t", o.Long)
+		}
+	}
+	return true, w.Flush()
+}
+
 func (e *Executor) ToEditorOutput(tasks []*ast.Task, noStatus bool, nested bool, long bool) (*editors.Namespace, error) {
 	var g errgroup.Group
 	editorTasks := make([]editors.Task, len(tasks))

internal/flags/flags.go

@@ -88,6 +88,7 @@ var (
 	Cert                string
 	CertKey             string
 	Interactive         bool
+	Tree                bool
 )
 
 func init() {
@@ -129,6 +130,7 @@ func init() {
 	pflag.BoolVarP(&ListJson, "json", "j", false, "Formats task list as JSON.")
 	pflag.StringVar(&TaskSort, "sort", "", "Changes the order of the tasks when listed. [default|alphanumeric|none].")
 	pflag.BoolVarP(&Long, "long", "L", false, "Show detailed task information when listing.")
+	pflag.BoolVarP(&Tree, "tree", "T", false, "Display tasks grouped by namespace.")
 	pflag.BoolVar(&Status, "status", false, "Exits with non-zero exit code if any of the given tasks is not up-to-date.")
 	pflag.BoolVar(&NoStatus, "no-status", false, "Ignore status when listing tasks as JSON")
 	pflag.BoolVar(&Nested, "nested", false, "Nest namespaces when listing tasks as JSON")
@@ -248,6 +250,14 @@ func Validate() error {
 		return errors.New("task: --nested only applies to --json with --list or --list-all")
 	}
 
+	if Tree && !List && !ListAll {
+		return errors.New("task: --tree only applies to --list or --list-all")
+	}
+
+	if Tree && ListJson {
+		return errors.New("task: --tree and --json are mutually exclusive")
+	}
+
 	// Validate certificate flags
 	if (Cert != "" && CertKey == "") || (Cert == "" && CertKey != "") {
 		return errors.New("task: --cert and --cert-key must be provided together")

internal/listing/helpers_test.go

@@ -0,0 +1,7 @@
+package listing_test
+
+import "github.com/go-task/task/v3/taskfile/ast"
+
+func newTask(name, desc string) *ast.Task {
+	return &ast.Task{Task: name, Desc: desc}
+}

internal/listing/tree.go

@@ -0,0 +1,62 @@
+package listing
+
+import (
+	"strings"
+
+	"github.com/go-task/task/v3/taskfile/ast"
+)
+
+// TaskGroup represents a set of tasks under a common top-level namespace.
+type TaskGroup struct {
+	Namespace string
+	Tasks     []*ast.Task
+}
+
+func (g TaskGroup) LocalName(t *ast.Task) string {
+	if g.Namespace == "" {
+		return t.Task
+	}
+	return strings.TrimPrefix(t.Task, g.Namespace+":")
+}
+
+// GroupByNamespace partitions tasks into groups by their top-level namespace.
+func GroupByNamespace(tasks []*ast.Task) []TaskGroup {
+	groupMap := make(map[string]int)
+	var groups []TaskGroup
+	for _, t := range tasks {
+		ns := topLevelNamespace(t.Task)
+		idx, exists := groupMap[ns]
+		if !exists {
+			idx = len(groups)
+			groupMap[ns] = idx
+			groups = append(groups, TaskGroup{Namespace: ns})
+		}
+		groups[idx].Tasks = append(groups[idx].Tasks, t)
+	}
+	return groups
+}
+
+func HasNamespacedGroups(groups []TaskGroup) bool {
+	for _, g := range groups {
+		if g.Namespace != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func HasRootGroup(groups []TaskGroup) bool {
+	for _, g := range groups {
+		if g.Namespace == "" {
+			return true
+		}
+	}
+	return false
+}
+
+func topLevelNamespace(taskName string) string {
+	if ns, _, found := strings.Cut(taskName, ":"); found {
+		return ns
+	}
+	return ""
+}

internal/listing/tree_test.go

@@ -0,0 +1,101 @@
+package listing_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/go-task/task/v3/internal/listing"
+	"github.com/go-task/task/v3/taskfile/ast"
+)
+
+func TestGroupByNamespace_Empty(t *testing.T) {
+	t.Parallel()
+	groups := listing.GroupByNamespace(nil)
+	assert.Empty(t, groups)
+}
+
+func TestGroupByNamespace_OnlyRoot(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("build", "Build"),
+		newTask("test", "Test"),
+	}
+	groups := listing.GroupByNamespace(tasks)
+	assert.Len(t, groups, 1)
+	assert.Equal(t, "", groups[0].Namespace)
+	assert.Len(t, groups[0].Tasks, 2)
+}
+
+func TestGroupByNamespace_OnlyNamespaced(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("ns1:build", "Build"),
+		newTask("ns1:test", "Test"),
+		newTask("ns2:deploy", "Deploy"),
+	}
+	groups := listing.GroupByNamespace(tasks)
+	assert.Len(t, groups, 2)
+	assert.Equal(t, "ns1", groups[0].Namespace)
+	assert.Len(t, groups[0].Tasks, 2)
+	assert.Equal(t, "ns2", groups[1].Namespace)
+	assert.Len(t, groups[1].Tasks, 1)
+}
+
+func TestGroupByNamespace_Mixed(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("build", "Build"),
+		newTask("ns1:lint", "Lint"),
+		newTask("ns1:test", "Test"),
+		newTask("deploy", "Deploy"),
+	}
+	groups := listing.GroupByNamespace(tasks)
+	assert.Len(t, groups, 2)
+	assert.Equal(t, "", groups[0].Namespace)
+	assert.Len(t, groups[0].Tasks, 2)
+	assert.Equal(t, "ns1", groups[1].Namespace)
+	assert.Len(t, groups[1].Tasks, 2)
+}
+
+func TestGroupByNamespace_PreservesOrder(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("z:first", ""),
+		newTask("a:second", ""),
+		newTask("m:third", ""),
+	}
+	groups := listing.GroupByNamespace(tasks)
+	assert.Len(t, groups, 3)
+	assert.Equal(t, "z", groups[0].Namespace)
+	assert.Equal(t, "a", groups[1].Namespace)
+	assert.Equal(t, "m", groups[2].Namespace)
+}
+
+func TestLocalName_Namespaced(t *testing.T) {
+	t.Parallel()
+	g := listing.TaskGroup{Namespace: "ns1"}
+	task := newTask("ns1:build", "Build")
+	assert.Equal(t, "build", g.LocalName(task))
+}
+
+func TestLocalName_Root(t *testing.T) {
+	t.Parallel()
+	g := listing.TaskGroup{Namespace: ""}
+	task := newTask("build", "Build")
+	assert.Equal(t, "build", g.LocalName(task))
+}
+
+func TestHasNamespacedGroups(t *testing.T) {
+	t.Parallel()
+	assert.False(t, listing.HasNamespacedGroups([]listing.TaskGroup{{Namespace: ""}}))
+	assert.True(t, listing.HasNamespacedGroups([]listing.TaskGroup{{Namespace: "ns"}}))
+	assert.True(t, listing.HasNamespacedGroups([]listing.TaskGroup{{Namespace: ""}, {Namespace: "ns"}}))
+}
+
+func TestHasRootGroup(t *testing.T) {
+	t.Parallel()
+	assert.True(t, listing.HasRootGroup([]listing.TaskGroup{{Namespace: ""}}))
+	assert.False(t, listing.HasRootGroup([]listing.TaskGroup{{Namespace: "ns"}}))
+	assert.True(t, listing.HasRootGroup([]listing.TaskGroup{{Namespace: ""}, {Namespace: "ns"}}))
+}

internal/logger/logger.go

@@ -35,6 +35,8 @@ var (
 	attrsFgHiYellow  = envColor("COLOR_BRIGHT_YELLOW", color.FgHiYellow)
 	attrsFgHiMagenta = envColor("COLOR_BRIGHT_MAGENTA", color.FgHiMagenta)
 	attrsFgHiRed     = envColor("COLOR_BRIGHT_RED", color.FgHiRed)
+	attrsBold        = envColor("COLOR_BOLD", color.Bold)
+	attrsDim         = envColor("COLOR_DIM", color.Faint)
 )
 
 type (
@@ -100,6 +102,14 @@ func BrightRed() PrintFunc {
 	return color.New(attrsFgHiRed...).FprintfFunc()
 }
 
+func Bold() PrintFunc {
+	return color.New(attrsBold...).FprintfFunc()
+}
+
+func Dim() PrintFunc {
+	return color.New(attrsDim...).FprintfFunc()
+}
+
 func envColor(name string, defaultColor color.Attribute) []color.Attribute {
 	// Fetch the environment variable
 	override := env.GetTaskEnv(name)