taskfile

Documentation

Index

• func FindRootDir(dir string) (string, error)
• func IsInternalTask(name string) bool
• type Cmd
  • func (c *Cmd) UnmarshalYAML(unmarshal func(any) error) error
• type Config
  • func LoadWithIncludes(dir string) (*Config, error)
  • func Parse(dir string) (*Config, error)
• type Dep
  • func (d *Dep) UnmarshalYAML(unmarshal func(any) error) error
• type Execution
• type Precondition
  • func (p *Precondition) UnmarshalYAML(unmarshal func(any) error) error
• type Requires
• type Runner
  • func NewRunner(tf *Config, cwd string) (*Runner, error)
  • func (r *Runner) ResetRan()
  • func (r *Runner) Run(name, cliArgs string, extraVars ...map[string]Var) error
  • func (r *Runner) Watch(ctx context.Context, name, cliArgs string, interval time.Duration) error
• type RunnerIO
• type ShellCommand
• type ShellCommandKind
• type ShellRunner
• type StringList
  • func (sl *StringList) UnmarshalYAML(unmarshal func(any) error) error
• type Task
  • func (t *Task) UnmarshalYAML(unmarshal func(any) error) error
• type TaskNotFoundError
  • func (e *TaskNotFoundError) Error() string
• type Var
  • func (v *Var) UnmarshalYAML(unmarshal func(any) error) error

Functions

func FindRootDir

func FindRootDir(dir string) (string, error)

FindRootDir walks up from dir to find the nearest directory containing a gogo.yaml.

func IsInternalTask

func IsInternalTask(name string) bool

IsInternalTask reports whether a task name is internal (its local segment starts with '_'). Only the part after the last colon is checked so 'ns:_helper' is internal but 'ns:public' is not. Internal tasks are hidden from --list, completion, and prefix matching.

Types

type Cmd

type Cmd struct {
	Cmd  string         `yaml:"cmd"`
	Task string         `yaml:"task"`
	Vars map[string]Var `yaml:"vars"`
}

Cmd represents a command in a task. It can be a simple string or a task reference.

func (*Cmd) UnmarshalYAML

func (c *Cmd) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML allows Cmd to be either a string or a map.

type Config

type Config struct {
	Version       string                    `yaml:"version"`
	Includes      []string                  `yaml:"includes"`
	Flatten       []string                  `yaml:"flatten"` // YAML files whose tasks merge into this config without a namespace
	Dotenv        []string                  `yaml:"dotenv"`
	Default       string                    `yaml:"default"` // task to run when none is given on the CLI; replaces the convention of declaring a `default` task
	Vars          map[string]Var            `yaml:"vars"`    // vars declared at the root (namespace "")
	Sources       map[string]StringList     `yaml:"sources"` // named source presets, referenced from task.Sources by name
	Secrets       map[string]string         `yaml:"secrets"` // named secret URIs (op://, aws-creds://, ...), referenced from task.Secrets
	Tasks         map[string]Task           `yaml:"tasks"`
	Dir           string                    `yaml:"-"`
	Interval      string                    `yaml:"interval"`
	Namespaces    map[string]string         `yaml:"-"` // dir -> namespace
	NamespaceDirs map[string]string         `yaml:"-"` // namespace -> dir (where each include's gogo.yaml lives, used to resolve `sh:` vars in their own working dir)
	NamespaceVars map[string]map[string]Var `yaml:"-"` // namespace -> vars declared at that namespace; not visible to sibling namespaces
	DotenvVars    map[string]string         `yaml:"-"` // resolved dotenv variables
}

Config represents a parsed gogo.yaml.

func LoadWithIncludes

func LoadWithIncludes(dir string) (*Config, error)

LoadWithIncludes parses a task file and resolves all includes into a flat task map.

func Parse

func Parse(dir string) (*Config, error)

Parse reads and parses a task file from the given directory.

type Dep

type Dep struct {
	Task string `yaml:"task"`
}

Dep represents a task dependency.

func (*Dep) UnmarshalYAML

func (d *Dep) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML allows Dep to be either a string or a map.

type Execution

type Execution struct {
	Task     string
	Command  string
	Dir      string
	Env      []string
	UseOpRun bool
}

Execution records a single command that was (or would be) executed.

type Precondition

type Precondition struct {
	Sh  string `yaml:"sh"`
	Msg string `yaml:"msg"`
}

Precondition defines a shell command that must succeed before a task runs.

func (*Precondition) UnmarshalYAML

func (p *Precondition) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML allows Precondition to be either a string (shell command) or a map.

type Requires

type Requires struct {
	Vars []string `yaml:"vars"`
	Env  []string `yaml:"env"`
}

Requires defines variables and environment variables that must be set for a task to run.

type Runner

type Runner struct {
	BaseEnv []string // base process environment (defaults to os.Environ() + dotenv)

	DryRun      bool        // if true, print commands without executing them
	Force       bool        // if true, ignore sources and generates (always run)
	ShellRunner ShellRunner // replaceable shell executor (defaults to real exec)
	IO          RunnerIO    // process streams used for logs and command stdio
	// contains filtered or unexported fields
}

Runner executes tasks from a loaded task file.

func NewRunner

func NewRunner(tf *Config, cwd string) (*Runner, error)

NewRunner creates a task runner for the given task file.

func (*Runner) ResetRan

func (r *Runner) ResetRan()

ResetRan clears the memoized task results, allowing tasks to run again. This is used by watch mode between iterations. Built-in git vars are re-resolved too because file edits between iterations may have changed the working tree's dirty state or HEAD.

func (*Runner) Run

func (r *Runner) Run(name, cliArgs string, extraVars ...map[string]Var) error

Run executes the named task. Extra vars (from task call sites) override task-level vars.

func (*Runner) Watch

func (r *Runner) Watch(ctx context.Context, name, cliArgs string, interval time.Duration) error

Watch runs the named task, then polls its sources and re-runs when they change. It stops gracefully when the context is cancelled.

type RunnerIO

type RunnerIO struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

RunnerIO contains process streams used by a Runner.

type ShellCommand

type ShellCommand struct {
	Kind     ShellCommandKind
	TaskName string
	Command  string
	Dir      string
	Env      []string
	UseOpRun bool
	Stdin    io.Reader
	Stdout   io.Writer
	Stderr   io.Writer
}

ShellCommand describes one shell invocation.

type ShellCommandKind

type ShellCommandKind string

ShellCommandKind identifies why a shell command is being run.

const (
	ShellCommandTask         ShellCommandKind = "task"
	ShellCommandPrecondition ShellCommandKind = "precondition"
	ShellCommandVar          ShellCommandKind = "var"
)

type ShellRunner

type ShellRunner interface {
	Run(req ShellCommand) error
	Output(req ShellCommand) ([]byte, error)
}

ShellRunner runs shell commands for task commands, preconditions, and shell variables.

type StringList

type StringList []string

StringList is a []string that can be unmarshalled from either a single string or a list.

func (*StringList) UnmarshalYAML

func (sl *StringList) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML allows StringList to be either a string or a sequence.

type Task

type Task struct {
	Cmds          []Cmd             `yaml:"cmds"`
	Deps          []Dep             `yaml:"deps"`
	Dir           string            `yaml:"dir"`
	Dotenv        []string          `yaml:"dotenv"`
	Env           map[string]string `yaml:"env"`
	Vars          map[string]Var    `yaml:"vars"`
	Secrets       StringList        `yaml:"secrets"` // names referencing entries in Config.Secrets
	Sources       StringList        `yaml:"sources"`
	Generates     StringList        `yaml:"generates"`
	Aliases       StringList        `yaml:"aliases"`
	Platforms     StringList        `yaml:"platforms"`
	Requires      Requires          `yaml:"requires"`
	Preconditions []Precondition    `yaml:"preconditions"`
	Silent        bool              `yaml:"silent"` // when true, suppress the per-cmd "[task] cmd" log line
	Desc          string            `yaml:"-"`      // set from YAML comments, not from a field
}

Task represents a single task definition.

func (*Task) UnmarshalYAML

func (t *Task) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML normalizes the singular "cmd" field into the "cmds" list.

type TaskNotFoundError

type TaskNotFoundError struct {
	Name        string   // the unresolved input as typed by the user
	Suggestions []string // best-effort 'did you mean' hints (may be empty)
}

TaskNotFoundError is returned when the user asks for a task name that doesn't resolve. It's a typed error so callers (notably the CLI) can react — for example, by printing the task list alongside the message — without parsing the formatted text.

func (*TaskNotFoundError) Error

func (e *TaskNotFoundError) Error() string

Error renders the message historically produced by resolveTask. The exact wording is part of the user-facing contract: tooling and tests grep for 'not found' and 'did you mean'.

type Var

type Var struct {
	Value string `yaml:"value"`
	Sh    string `yaml:"sh"`
}

Var represents a variable value. It can be a static string or a shell command.

func (*Var) UnmarshalYAML

func (v *Var) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML allows Var to be either a string or a map with sh.