feat(list): add filter pattern and match highlighting

Adds an optional positional filter argument to --list and --list-all
that narrows output by matching against task names and descriptions.
Matched text is bolded in the output.

Refs: #2091

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

Author: trevor-vaughan

cmd/task/task.go

@@ -139,6 +139,13 @@ func run() error {
 		return os.RemoveAll(cachePath)
 	}
 
+	// Extract an optional filter pattern from positional args when listing
+	var filterPattern string
+	if flags.List || flags.ListAll {
+		if positionalArgs := pflag.Args(); len(positionalArgs) > 0 {
+			filterPattern = positionalArgs[0]
+		}
+	}
 	listOptions := task.NewListOptions(
 		flags.List,
 		flags.ListAll,
@@ -147,6 +154,8 @@ func run() error {
 		flags.Nested,
 		flags.Long,
 		flags.Tree,
+		filterPattern,
+		flags.TaskSort,
 	)
 	if listOptions.ShouldListTasks() {
 		if flags.Silent {

formatter_test.go

@@ -291,6 +291,80 @@ func TestListTreeLong(t *testing.T) {
 	)
 }
 
+func TestListFilter(t *testing.T) {
+	t.Parallel()
+
+	NewFormatterTest(t,
+		WithExecutorOptions(
+			task.WithDir("testdata/list_filter"),
+		),
+		WithListOptions(task.ListOptions{
+			ListOnlyTasksWithDescriptions: true,
+			Filter:                        "docker",
+		}),
+	)
+}
+
+func TestListFilterNoMatch(t *testing.T) {
+	t.Parallel()
+
+	NewFormatterTest(t,
+		WithExecutorOptions(
+			task.WithDir("testdata/list_filter"),
+		),
+		WithListOptions(task.ListOptions{
+			ListOnlyTasksWithDescriptions: true,
+			Filter:                        "nonexistent",
+		}),
+	)
+}
+
+func TestListTreeFilter(t *testing.T) {
+	t.Parallel()
+
+	NewFormatterTest(t,
+		WithExecutorOptions(
+			task.WithDir("testdata/list_tree_filter"),
+		),
+		WithListOptions(task.ListOptions{
+			ListOnlyTasksWithDescriptions: true,
+			Tree:                          true,
+			Filter:                        "docker",
+		}),
+	)
+}
+
+func TestListTreeFilterLong(t *testing.T) {
+	t.Parallel()
+
+	NewFormatterTest(t,
+		WithExecutorOptions(
+			task.WithDir("testdata/list_tree_filter"),
+		),
+		WithListOptions(task.ListOptions{
+			ListOnlyTasksWithDescriptions: true,
+			Tree:                          true,
+			Long:                          true,
+			Filter:                        "docker",
+		}),
+	)
+}
+
+func TestListFlatFilterLong(t *testing.T) {
+	t.Parallel()
+
+	NewFormatterTest(t,
+		WithExecutorOptions(
+			task.WithDir("testdata/list_tree_filter"),
+		),
+		WithListOptions(task.ListOptions{
+			ListOnlyTasksWithDescriptions: true,
+			Long:                          true,
+			Filter:                        "docker",
+		}),
+	)
+}
+
 func TestJsonListLong(t *testing.T) {
 	t.Parallel()
 

help.go

@@ -28,10 +28,12 @@ type ListOptions struct {
 	Nested                        bool
 	Long                          bool
 	Tree                          bool
+	Filter                        string
+	SortMode                      string
 }
 
 // NewListOptions creates a new ListOptions instance
-func NewListOptions(list, listAll, listAsJson, noStatus, nested, long, tree bool) ListOptions {
+func NewListOptions(list, listAll, listAsJson, noStatus, nested, long, tree bool, filter, sortMode string) ListOptions {
 	return ListOptions{
 		ListOnlyTasksWithDescriptions: list,
 		ListAllTasks:                  listAll,
@@ -40,6 +42,8 @@ func NewListOptions(list, listAll, listAsJson, noStatus, nested, long, tree bool
 		Nested:                        nested,
 		Long:                          long,
 		Tree:                          tree,
+		Filter:                        filter,
+		SortMode:                      sortMode,
 	}
 }
 
@@ -69,6 +73,9 @@ func (e *Executor) ListTasks(o ListOptions) (bool, error) {
 	if err != nil {
 		return false, err
 	}
+	if o.Filter != "" {
+		tasks = listing.FilterTasks(tasks, o.Filter)
+	}
 	if o.FormatTaskListAsJSON {
 		output, err := e.ToEditorOutput(tasks, o.NoStatus, o.Nested, o.Long)
 		if err != nil {
@@ -84,7 +91,9 @@ func (e *Executor) ListTasks(o ListOptions) (bool, error) {
 		return len(tasks) > 0, nil
 	}
 	if len(tasks) == 0 {
-		if o.ListOnlyTasksWithDescriptions {
+		if o.Filter != "" {
+			e.Logger.Outf(logger.Yellow, "task: No tasks matching %q\n", o.Filter)
+		} else if o.ListOnlyTasksWithDescriptions {
 			e.Logger.Outf(logger.Yellow, "task: No tasks with description available. Try --list-all to list all tasks\n")
 		} else if o.ListAllTasks {
 			e.Logger.Outf(logger.Yellow, "task: No tasks available\n")
@@ -100,7 +109,7 @@ func (e *Executor) ListTasks(o ListOptions) (bool, error) {
 	w := tabwriter.NewWriter(e.Stdout, 0, 8, 6, ' ', 0)
 	for _, task := range tasks {
 		e.Logger.FOutf(w, logger.Yellow, "* ")
-		e.Logger.FOutf(w, logger.Green, task.Task)
+		e.writeHighlighted(w, logger.Green, task.Task, o.Filter)
 		desc := strings.ReplaceAll(task.Desc, "\n", " ")
 		e.Logger.FOutf(w, logger.Default, ": \t%s", desc)
 		if len(task.Aliases) > 0 {
@@ -115,6 +124,21 @@ func (e *Executor) ListTasks(o ListOptions) (bool, error) {
 	return true, nil
 }
 
+func (e *Executor) writeHighlighted(w io.Writer, baseColor logger.Color, text, filter string) {
+	if filter == "" || listing.IsGlobPattern(filter) {
+		e.Logger.FOutf(w, baseColor, "%s", text)
+		return
+	}
+	idx := strings.Index(strings.ToLower(text), strings.ToLower(filter))
+	if idx == -1 {
+		e.Logger.FOutf(w, baseColor, "%s", text)
+		return
+	}
+	e.Logger.FOutf(w, baseColor, "%s", text[:idx])
+	e.Logger.FOutf(w, logger.Bold, "%s", text[idx:idx+len(filter)])
+	e.Logger.FOutf(w, baseColor, "%s", text[idx+len(filter):])
+}
+
 func (e *Executor) writeTaskDetails(w io.Writer, task *ast.Task, indent string, long bool) {
 	if listing.HasRequires(task) {
 		e.Logger.FOutf(w, logger.Default, indent)
@@ -173,7 +197,7 @@ func (e *Executor) listTasksTree(tasks []*ast.Task, o ListOptions) (bool, error)
 	groups := listing.GroupByNamespace(tasks)
 	hasNamespaced := listing.HasNamespacedGroups(groups)
 	hasRoot := listing.HasRootGroup(groups)
-	showSeparator := hasNamespaced && hasRoot
+	showSeparator := hasNamespaced && hasRoot && (o.SortMode == "" || o.SortMode == "default")
 
 	// Move root group to end so namespaced groups appear first
 	if showSeparator {
@@ -212,7 +236,8 @@ func (e *Executor) listTasksTree(tasks []*ast.Task, o ListOptions) (bool, error)
 			if task.Internal {
 				nameColor = logger.Dim
 			}
-			e.Logger.FOutf(w, nameColor, "%s%s", indent, name)
+			e.Logger.FOutf(w, nameColor, "%s", indent)
+			e.writeHighlighted(w, nameColor, name, o.Filter)
 			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, ", "))

internal/listing/filter.go

@@ -0,0 +1,52 @@
+package listing
+
+import (
+	"path"
+	"strings"
+
+	"github.com/go-task/task/v3/taskfile/ast"
+)
+
+func IsGlobPattern(pattern string) bool {
+	return strings.ContainsAny(pattern, "*?[")
+}
+
+// FilterTasks returns tasks whose name or description matches the pattern.
+func FilterTasks(tasks []*ast.Task, pattern string) []*ast.Task {
+	if pattern == "" {
+		return tasks
+	}
+	if IsGlobPattern(pattern) {
+		return filterByGlob(tasks, pattern)
+	}
+	return filterBySubstring(tasks, pattern)
+}
+
+func filterBySubstring(tasks []*ast.Task, pattern string) []*ast.Task {
+	lower := strings.ToLower(pattern)
+	var result []*ast.Task
+	for _, t := range tasks {
+		nameLower := strings.ToLower(t.Task)
+		descLower := strings.ToLower(t.Desc)
+		if strings.Contains(nameLower, lower) ||
+			strings.Contains(descLower, lower) {
+			result = append(result, t)
+		}
+	}
+	return result
+}
+
+func filterByGlob(tasks []*ast.Task, pattern string) []*ast.Task {
+	lowerPattern := strings.ToLower(pattern)
+	var result []*ast.Task
+	for _, t := range tasks {
+		matched, err := path.Match(lowerPattern, strings.ToLower(t.Task))
+		if err != nil {
+			return filterBySubstring(tasks, pattern)
+		}
+		if matched {
+			result = append(result, t)
+		}
+	}
+	return result
+}

internal/listing/filter_test.go

@@ -0,0 +1,100 @@
+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 TestIsGlobPattern(t *testing.T) {
+	t.Parallel()
+	assert.True(t, listing.IsGlobPattern("docker:*"))
+	assert.True(t, listing.IsGlobPattern("test?"))
+	assert.True(t, listing.IsGlobPattern("[ab]"))
+	assert.False(t, listing.IsGlobPattern("docker"))
+	assert.False(t, listing.IsGlobPattern(""))
+}
+
+func TestFilterTasks_EmptyPattern(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{newTask("build", "Build it")}
+	result := listing.FilterTasks(tasks, "")
+	assert.Equal(t, tasks, result)
+}
+
+func TestFilterTasks_Substring(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("docker:build", "Build image"),
+		newTask("docker:push", "Push image"),
+		newTask("test:unit", "Run unit tests"),
+		newTask("lint", "Run linters"),
+	}
+	result := listing.FilterTasks(tasks, "docker")
+	assert.Equal(t, []string{"docker:build", "docker:push"}, taskNames(result))
+}
+
+func TestFilterTasks_SubstringCaseInsensitive(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("Docker:Build", "Build image"),
+		newTask("lint", "Run linters"),
+	}
+	result := listing.FilterTasks(tasks, "docker")
+	assert.Equal(t, []string{"Docker:Build"}, taskNames(result))
+}
+
+func TestFilterTasks_MatchesDescription(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("build", "Build the Docker image"),
+		newTask("lint", "Run linters"),
+	}
+	result := listing.FilterTasks(tasks, "docker")
+	assert.Equal(t, []string{"build"}, taskNames(result))
+}
+
+func TestFilterTasks_NamespacePrefix(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("docker:build", "Build image"),
+		newTask("docker:push", "Push image"),
+		newTask("undocker", "Not a namespace match but substring"),
+	}
+	result := listing.FilterTasks(tasks, "docker")
+	assert.Equal(t, []string{"docker:build", "docker:push", "undocker"}, taskNames(result))
+}
+
+func TestFilterTasks_Glob(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("docker:build", "Build image"),
+		newTask("docker:push", "Push image"),
+		newTask("test:unit", "Run unit tests"),
+		newTask("lint", "Run linters"),
+	}
+	result := listing.FilterTasks(tasks, "docker:*")
+	assert.Equal(t, []string{"docker:build", "docker:push"}, taskNames(result))
+}
+
+func TestFilterTasks_GlobNoMatch(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("build", "Build it"),
+		newTask("lint", "Run linters"),
+	}
+	result := listing.FilterTasks(tasks, "xyz:*")
+	assert.Empty(t, result)
+}
+
+func TestFilterTasks_NoMatch(t *testing.T) {
+	t.Parallel()
+	tasks := []*ast.Task{
+		newTask("build", "Build it"),
+	}
+	result := listing.FilterTasks(tasks, "zzzzz")
+	assert.Empty(t, result)
+}

internal/listing/helpers_test.go

@@ -5,3 +5,11 @@ import "github.com/go-task/task/v3/taskfile/ast"
 func newTask(name, desc string) *ast.Task {
 	return &ast.Task{Task: name, Desc: desc}
 }
+
+func taskNames(tasks []*ast.Task) []string {
+	names := make([]string, len(tasks))
+	for i, t := range tasks {
+		names[i] = t.Task
+	}
+	return names
+}

testdata/list_filter/Taskfile.yml

@@ -0,0 +1,22 @@
+version: '3'
+
+tasks:
+  docker:build:
+    desc: Build the Docker image
+    cmds:
+      - docker build .
+
+  docker:push:
+    desc: Push the Docker image
+    cmds:
+      - docker push
+
+  test:unit:
+    desc: Run unit tests
+    cmds:
+      - go test ./...
+
+  lint:
+    desc: Run linters
+    cmds:
+      - golangci-lint run

testdata/list_filter/testdata/TestListFilter.golden

@@ -0,0 +1,3 @@
+task: Available tasks for this project:
+* docker:build:       Build the Docker image
+* docker:push:        Push the Docker image

testdata/list_filter/testdata/TestListFilterNoMatch.golden

@@ -0,0 +1 @@
+task: No tasks matching "nonexistent"