feat: command timeouts (#2898)

Author: vmaerten

CHANGELOG.md

@@ -44,6 +44,13 @@
 - Added Nushell completions, available via `task --completion nu`. They complete
   task names and aliases, every flag with its description, and the values of
   `--completion`, `--output` and `--sort` (#2966 by @vmaerten).
+- :warning: Added a per-command `timeout` that terminates a command once it
+  exceeds the given duration (Go duration syntax). It covers shell commands,
+  task calls, deferred commands, `deps` and the `if` condition, obeys
+  `ignore_error`, and reports exit code `124`. Callers that join a `run: once`
+  or `when_changed` task already running now honor their own `timeout`, and
+  inherit that task's failure instead of being told it succeeded (#1569, #2898
+  by @vmaerten).
 
 ## v3.52.0 - 2026-07-02
 

errors/errors.go

@@ -39,6 +39,7 @@ const (
 	CodeTaskCancelled
 	CodeTaskMissingRequiredVars
 	CodeTaskNotAllowedVars
+	CodeTaskTimedOut
 )
 
 // TaskError extends the standard error interface with a Code method. This code will

errors/errors_task.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"strings"
+	"time"
 
 	"mvdan.cc/sh/v3/interp"
 )
@@ -51,13 +52,36 @@ func (err *TaskRunError) TaskExitCode() int {
 	if errors.As(err.Err, &exit) {
 		return int(exit)
 	}
+	var timeout *TaskTimeoutError
+	if errors.As(err.Err, &timeout) {
+		return TimeoutExitCode
+	}
 	return err.Code()
 }
 
 func (err *TaskRunError) Unwrap() error {
 	return err.Err
 }
 
+// TimeoutExitCode is what a killed command reports in place of the exit status
+// it never got, following the convention of timeout(1).
+const TimeoutExitCode = 124
+
+// TaskTimeoutError is returned when a command exceeds the timeout it declared.
+// It must not unwrap to context.DeadlineExceeded, which --watch swallows.
+type TaskTimeoutError struct {
+	TaskName string
+	Timeout  time.Duration
+}
+
+func (err *TaskTimeoutError) Error() string {
+	return fmt.Sprintf(`task: [%s] command timeout exceeded (%s)`, err.TaskName, err.Timeout)
+}
+
+func (err *TaskTimeoutError) Code() int {
+	return CodeTaskTimedOut
+}
+
 // TaskInternalError when the user attempts to invoke a task that is internal.
 type TaskInternalError struct {
 	TaskName string

executor.go

@@ -1,7 +1,6 @@
 package task
 
 import (
-	"context"
 	"io"
 	"os"
 	"sync"
@@ -80,7 +79,7 @@ type (
 		concurrencySemaphore chan struct{}
 		taskCallCount        map[string]*int32
 		mkdirMutexMap        map[string]*sync.Mutex
-		executionHashes      map[string]context.Context
+		executionHashes      map[string]*executionState
 		executionHashesMutex sync.Mutex
 		watchedDirs          *xsync.Map[string, bool]
 	}
@@ -108,7 +107,7 @@ func NewExecutor(opts ...ExecutorOption) *Executor {
 		concurrencySemaphore: nil,
 		taskCallCount:        map[string]*int32{},
 		mkdirMutexMap:        map[string]*sync.Mutex{},
-		executionHashes:      map[string]context.Context{},
+		executionHashes:      map[string]*executionState{},
 		executionHashesMutex: sync.Mutex{},
 	}
 	e.Options(opts...)

setup.go

@@ -261,7 +261,7 @@ func (e *Executor) setupDefaults() {
 }
 
 func (e *Executor) setupConcurrencyState() {
-	e.executionHashes = make(map[string]context.Context)
+	e.executionHashes = make(map[string]*executionState)
 
 	e.taskCallCount = make(map[string]*int32, e.Taskfile.Tasks.Len())
 	e.mkdirMutexMap = make(map[string]*sync.Mutex, e.Taskfile.Tasks.Len())

task.go

@@ -266,14 +266,20 @@ func (e *Executor) RunTask(ctx context.Context, call *Call) error {
 					e.Logger.VerboseErrf(logger.Yellow, "task: error cleaning status on error: %v\n", err2)
 				}
 
+				if t.IgnoreError && isCommandFailure(err) {
+					e.Logger.VerboseErrf(logger.Yellow, "task: task error ignored: %v\n", err)
+					continue
+				}
+
+				e.Logger.VerboseErrf(logger.Red, "task: %q failed: %v\n", call.Task, err)
+
 				var exitCode interp.ExitStatus
-				if errors.As(err, &exitCode) {
-					if t.IgnoreError {
-						e.Logger.VerboseErrf(logger.Yellow, "task: task error ignored: %v\n", err)
-						continue
-					}
-					e.Logger.VerboseErrf(logger.Red, "task: %q failed: %v\n", call.Task, err)
+				var timeout *errors.TaskTimeoutError
+				switch {
+				case errors.As(err, &exitCode):
 					deferredExitCode = uint8(exitCode)
+				case errors.As(err, &timeout):
+					deferredExitCode = errors.TimeoutExitCode
 				}
 
 				return err
@@ -316,11 +322,20 @@ func (e *Executor) runDeps(ctx context.Context, t *ast.Task) error {
 
 	for _, d := range t.Deps {
 		g.Go(func() error {
-			err := e.RunTask(ctx, &Call{Task: d.Task, Vars: d.Vars, Silent: d.Silent, Indirect: true})
-			if err != nil {
-				return err
+			depCtx := ctx
+			var timeout *errors.TaskTimeoutError
+			if d.Timeout > 0 {
+				timeout = &errors.TaskTimeoutError{TaskName: d.Task, Timeout: d.Timeout}
+				var cancel context.CancelFunc
+				depCtx, cancel = context.WithTimeoutCause(ctx, d.Timeout, timeout)
+				defer cancel()
 			}
-			return nil
+
+			err := e.RunTask(depCtx, &Call{Task: d.Task, Vars: d.Vars, Silent: d.Silent, Indirect: true})
+			if err != nil && timedOut(depCtx, timeout) {
+				return timeout
+			}
+			return err
 		})
 	}
 
@@ -354,13 +369,25 @@ func (e *Executor) runDeferred(t *ast.Task, call *Call, i int, vars *ast.Vars, d
 func (e *Executor) runCommand(ctx context.Context, t *ast.Task, call *Call, i int) error {
 	cmd := t.Cmds[i]
 
+	// In place before the if condition, which would otherwise run unbounded.
+	var timeout *errors.TaskTimeoutError
+	if cmd.Timeout > 0 {
+		timeout = &errors.TaskTimeoutError{TaskName: t.Name(), Timeout: cmd.Timeout}
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeoutCause(ctx, cmd.Timeout, timeout)
+		defer cancel()
+	}
+
 	// Check if condition for any command type
 	if strings.TrimSpace(cmd.If) != "" {
 		if err := execext.RunCommand(ctx, &execext.RunCommandOptions{
 			Command: cmd.If,
 			Dir:     t.Dir,
 			Env:     env.Get(t),
 		}); err != nil {
+			if timedOut(ctx, timeout) {
+				return timeout
+			}
 			e.Logger.VerboseOutf(logger.Yellow, "task: [%s] if condition not met - skipped\n", t.Name())
 			return nil
 		}
@@ -372,8 +399,10 @@ func (e *Executor) runCommand(ctx context.Context, t *ast.Task, call *Call, i in
 		defer reacquire()
 
 		err := e.RunTask(ctx, &Call{Task: cmd.Task, Vars: cmd.Vars, Silent: cmd.Silent, Indirect: true})
-		var exitCode interp.ExitStatus
-		if errors.As(err, &exitCode) && cmd.IgnoreError {
+		if err != nil && timedOut(ctx, timeout) {
+			err = timeout
+		}
+		if cmd.IgnoreError && isCommandFailure(err) {
 			e.Logger.VerboseErrf(logger.Yellow, "task: [%s] task error ignored: %v\n", t.Name(), err)
 			return nil
 		}
@@ -416,8 +445,10 @@ func (e *Executor) runCommand(ctx context.Context, t *ast.Task, call *Call, i in
 		if closeErr := closer(err); closeErr != nil {
 			e.Logger.Errf(logger.Red, "task: unable to close writer: %v\n", closeErr)
 		}
-		var exitCode interp.ExitStatus
-		if errors.As(err, &exitCode) && cmd.IgnoreError {
+		if err != nil && timedOut(ctx, timeout) {
+			err = timeout
+		}
+		if cmd.IgnoreError && isCommandFailure(err) {
 			e.Logger.VerboseErrf(logger.Yellow, "task: [%s] command error ignored: %v\n", t.Name(), err)
 			return nil
 		}
@@ -427,6 +458,27 @@ func (e *Executor) runCommand(ctx context.Context, t *ast.Task, call *Call, i in
 	}
 }
 
+// isCommandFailure reports whether the command failed on its own terms - a
+// non-zero exit status or its timeout - rather than Task failing to run it.
+func isCommandFailure(err error) bool {
+	var exitCode interp.ExitStatus
+	var timeout *errors.TaskTimeoutError
+	return errors.As(err, &exitCode) || errors.As(err, &timeout)
+}
+
+// timedOut reports whether ctx was cancelled by the given timeout rather than by
+// an inherited deadline, which a derived context reports as its own.
+func timedOut(ctx context.Context, timeout *errors.TaskTimeoutError) bool {
+	return timeout != nil && errors.Is(context.Cause(ctx), timeout)
+}
+
+// executionState is the outcome of a task execution, shared with the callers
+// that join it. err is written before done is closed; read it only once closed.
+type executionState struct {
+	done chan struct{}
+	err  error
+}
+
 func (e *Executor) startExecution(ctx context.Context, t *ast.Task, execute func(ctx context.Context) error) error {
 	h, err := e.GetHash(t)
 	if err != nil {
@@ -439,25 +491,41 @@ func (e *Executor) startExecution(ctx context.Context, t *ast.Task, execute func
 
 	e.executionHashesMutex.Lock()
 
-	if otherExecutionCtx, ok := e.executionHashes[h]; ok {
+	if other, ok := e.executionHashes[h]; ok {
 		e.executionHashesMutex.Unlock()
 		e.Logger.VerboseErrf(logger.Magenta, "task: skipping execution of task: %s\n", h)
 
 		// Release our execution slot to avoid blocking other tasks while we wait
 		reacquire := e.releaseConcurrencyLimit()
 		defer reacquire()
 
-		<-otherExecutionCtx.Done()
-		return nil
-	}
+		// A finished execution wins even if our context is done: there is
+		// nothing left to wait for, and select would otherwise pick at random.
+		select {
+		case <-other.done:
+			return other.err
+		default:
+		}
 
-	ctx, cancel := context.WithCancel(ctx)
-	defer cancel()
+		select {
+		case <-other.done:
+			// Its outcome is ours. Returning nil would hide an execution that
+			// failed, or that another caller's timeout killed.
+			return other.err
+		case <-ctx.Done():
+			// We did not start it, so we can only stop waiting. Report the cause
+			// so that our own timeout surfaces as one.
+			return context.Cause(ctx)
+		}
+	}
 
-	e.executionHashes[h] = ctx
+	state := &executionState{done: make(chan struct{})}
+	e.executionHashes[h] = state
 	e.executionHashesMutex.Unlock()
 
-	return execute(ctx)
+	defer close(state.done)
+	state.err = execute(ctx)
+	return state.err
 }
 
 // FindMatchingTasks returns a list of tasks that match the given call. A task