task

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 13, 2026 License: MIT Imports: 48 Imported by: 0

README

rite

An idempotent task runner with Unix-native variable precedence.

Status: pre-1.0, usable. Binary builds, test suite is green, SPEC's variable precedence model and ${VAR} shell-native preprocessor are both live. rite migrate converts a Taskfile.yml to a Ritefile.yml and flags anything that changes meaning under the new semantics. Docs site and v1.0.0 tag are still to come. See SPEC.md for the design contract.

Install

From source (requires Go 1.25+):

go install github.com/clintmod/rite/cmd/rite@latest

Use

rite --init                 # writes Ritefile.yml
rite <task>                 # runs a task
rite --list-all             # show all tasks
rite --migrate Taskfile.yml # convert a go-task Taskfile to a Ritefile

The five-second mental model: variables are first-in-wins. Shell env beats CLI args beats Ritefile defaults. Task-scope vars: are defaults only; if any higher tier sets the name, the task value is ignored.

What is this?

rite is a task runner in the same space as make, just, and go-task — you describe tasks in a declarative file, and the tool runs them with dependency resolution, parameters, and shell invocation.

The thing that makes rite different is how it handles variables. In one sentence: the value you set closest to the user wins. Your shell environment overrides everything. Your CLI arguments override the Ritefile. Internal vars: blocks declare defaults, not mandates.

This is how Unix has worked for 50 years. It is not how go-task works.

Why does this exist?

rite began as a hard fork of go-task/task. The upstream project has a variable model where a task's own vars: block overrides CLI arguments and shell environment — the inverse of every Unix precedent. A decade of bugs trace to this choice, and the upstream's proposed redesign preserves the inversion.

rite takes the opposite position: variable precedence should be first-in-wins, scoped sandboxes should be real, and dynamic variable evaluation should be pure.

See SPEC.md for the full design contract, including:

  • The 8-tier variable precedence model
  • Scoping rules for included Ritefiles
  • Dynamic (sh:) variable semantics
  • vars / env unification
  • Template syntax (${VAR} primary, Go-template secondary)
  • File format (Ritefile)
  • Compatibility with go-task (none — rite migrate converts one-way)

Relationship to go-task

rite imports go-task's git history to preserve attribution under its MIT license, but rite is not a compatibility fork:

  • Different binary (rite, not task)
  • Different file format (Ritefile, not Taskfile.yml)
  • Incompatible variable semantics
  • No intention to merge upstream changes that conflict with the SPEC
  • One-way migration tool only

The original project is excellent software with a design choice its creators do not want to revisit. rite exists for users who want the different choice.

License

MIT. See LICENSE. Original copyright © 2016 Andrey Nering; fork contributions © 2026 Clint Modien.

Roadmap

  • Phase 0: Repo set up, spec drafted.
  • Phase 1: Rebrand — module path, binary name, file format discovery.
  • Phase 1.5: Cosmetic polish — log prefix, error strings, rite --init.
  • Phase 2: First-in-wins getVariables(), per-resolution dynamic-var cache.
  • Phase 3: Test fixture audit and rewrite; include-site var precedence fix.
  • Phase 4: ${VAR} preprocessor, export: false opt-out, vars/env unified.
  • Phase 5 (in progress): rite migrate tool ✅ · docs site · v1.0.0 release.

Migrating from go-task

rite is an intentional semantic break from go-task, not a drop-in replacement. The five user-visible changes:

  1. Task-scope vars: are defaults only. If the entrypoint sets FOO, a task-scope FOO is ignored. Upstream's last-in-wins model is inverted.
  2. Task-scope env: is also defaults only. Same rule, applied to env blocks.
  3. Task-level dotenv: files don't override entrypoint env. Same rule.
  4. vars: auto-exports to the cmd shell environ. Add export: false on any var holding a secret that shouldn't leak.
  5. Shell env always wins over Ritefile env: SPEC tier 1 has no opt-out.

Run rite --migrate <path/to/Taskfile.yml> and it will: (a) write a Ritefile.yml with include-paths rewritten, and (b) emit warnings to stderr for every site where the old and new meanings differ (OVERRIDE-VAR, OVERRIDE-ENV, DOTENV-ENTRY, SECRET-VAR, SCHEMA-URL).

Documentation

Index

Constants

View Source 
const (
	// MaximumTaskCall is the max number of times a task can be called.
	// This exists to prevent infinite loops on cyclic dependencies
	MaximumTaskCall = 1000
)

Variables

View Source 
var DefaultTaskfile string
View Source 
var ErrPreconditionFailed = errors.New("rite: precondition not met")

ErrPreconditionFailed is returned when a precondition fails

Functions

func Completion 

func Completion(completion string) (string, error)

func FilterOutInternal 

func FilterOutInternal(task *ast.Task) bool

FilterOutInternal removes all tasks that are marked as internal.

func FilterOutNoDesc 

func FilterOutNoDesc(task *ast.Task) bool

FilterOutNoDesc removes all tasks that do not contain a description.

func InitTaskfile 

func InitTaskfile(path string) (string, error)

InitTaskfile creates a new Taskfile at path.

path can be either a file path or a directory path. If path is a directory, path/Taskfile.yml will be created.

The final file path is always returned and may be different from the input path.

func Migrate 

func Migrate(srcPath string, warn io.Writer) (dstPath string, err error)

Migrate reads a go-task Taskfile at srcPath, writes a converted Ritefile to the same directory, and emits a warning for every construct the fork's first-in-wins semantics would silently change the meaning of. Warnings go to warn; any fatal parse error is returned.

The tool does NOT attempt a deep structural rewrite — upstream's YAML is a near-superset of ours and most of it round-trips unchanged. What we DO transform on disk:

  • Input file is copied to <dir>/Ritefile<ext>; `Taskfile` substring in include-path literals is rewritten to `Ritefile`.

Everything else flows through verbatim, preserving user comments and formatting (we string-substitute rather than re-serialize the AST).

Detected semantic drifts get printed as `rite migrate: <warn-code>: …` lines so they're grep-friendly in CI. The five warning classes mirror the user-visible breaks documented in Phase 4 of the operating manual: 

OVERRIDE-VAR    task-scope vars: key shadowed by an entrypoint vars: key
                — under SPEC tier 7 the task value is now a default only.
OVERRIDE-ENV    same, for env: blocks.
DOTENV-ENTRY    task-level dotenv file whose keys collide with
                entrypoint env — entrypoint now wins.
SECRET-VAR      var name pattern-matches a secret (TOKEN/KEY/SECRET/
                PASSWORD/…) and lacks `export: false` — rite auto-exports
                `vars:` now, so this would leak to every cmd shell.
SCHEMA-URL      `# yaml-language-server: $schema=…taskfile.dev/schema.json`
                left in the file — cosmetic pointer at upstream docs.

func RitefilePathForTest 

func RitefilePathForTest(srcPath string) string

RitefilePathForTest exports ritefilePath under a test-only name so migrate_test.go can table-test filename mapping without promoting the helper to the public API.

func ShouldIgnore 

func ShouldIgnore(path string) bool

Types

type Call 

type Call struct {
	Task     string
	Vars     *ast.Vars
	Silent   bool
	Indirect bool // True if the task was called by another task
}

Call is the parameters to a task call

type Compiler 

type Compiler struct {
	Dir            string
	Entrypoint     string
	UserWorkingDir string

	TaskfileEnv  *ast.Vars
	TaskfileVars *ast.Vars

	Logger *logger.Logger
}

func (*Compiler) FastGetVariables 

func (c *Compiler) FastGetVariables(t *ast.Task, call *Call) (*ast.Vars, error)

func (*Compiler) GetTaskfileVariables 

func (c *Compiler) GetTaskfileVariables() (*ast.Vars, error)

func (*Compiler) GetVariables 

func (c *Compiler) GetVariables(t *ast.Task, call *Call) (*ast.Vars, error)

func (*Compiler) HandleDynamicVar 

func (c *Compiler) HandleDynamicVar(v ast.Var, dir string, e []string, cache map[string]string) (string, error)

HandleDynamicVar resolves a `sh:` variable. The optional cache argument is the per-resolution dedupe map: within one getVariables / compiledTask invocation, an identical `sh:` string resolves once. Across invocations (different tasks, different environments) each call evaluates independently, which is what SPEC §Dynamic Variables mandates — the upstream muDynamicCache keyed globally by command string caused cross-task pollution. Pass nil to disable caching entirely.

type Executor 

type Executor struct {
	// Flags
	Dir                 string
	Entrypoint          string
	TempDir             TempDir
	Force               bool
	ForceAll            bool
	Insecure            bool
	Download            bool
	Offline             bool
	TrustedHosts        []string
	Timeout             time.Duration
	CacheExpiryDuration time.Duration
	RemoteCacheDir      string
	CACert              string
	Cert                string
	CertKey             string
	Watch               bool
	Verbose             bool
	Silent              bool
	DisableFuzzy        bool
	AssumeYes           bool
	AssumeTerm          bool // Used for testing
	Interactive         bool
	Dry                 bool
	Summary             bool
	Parallel            bool
	Color               bool
	Concurrency         int
	Interval            time.Duration
	Failfast            bool

	// I/O
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer

	// Internal
	Taskfile           *ast.Taskfile
	Logger             *logger.Logger
	Compiler           *Compiler
	Output             output.Output
	OutputStyle        ast.Output
	TaskSorter         sort.Sorter
	UserWorkingDir     string
	EnableVersionCheck bool
	// contains filtered or unexported fields
}

An Executor is used for processing Taskfile(s) and executing the task(s) within them.

func NewExecutor 

func NewExecutor(opts ...ExecutorOption) *Executor

NewExecutor creates a new Executor and applies the given functional options to it.

func (*Executor) CompiledTask 

func (e *Executor) CompiledTask(call *Call) (*ast.Task, error)

CompiledTask returns a copy of a task, but replacing variables in almost all properties using the Go template package.

func (*Executor) CompiledTaskForTaskList 

func (e *Executor) CompiledTaskForTaskList(call *Call) (*ast.Task, error)

func (*Executor) FastCompiledTask 

func (e *Executor) FastCompiledTask(call *Call) (*ast.Task, error)

FastCompiledTask is like CompiledTask, but it skippes dynamic variables.

func (*Executor) FindMatchingTasks 

func (e *Executor) FindMatchingTasks(call *Call) ([]*MatchingTask, error)

FindMatchingTasks returns a list of tasks that match the given call. A task matches a call if its name is equal to the call's task name, or one of aliases, or if it matches a wildcard pattern. The function returns a list of MatchingTask structs, each containing a task and a list of wildcards that were matched. If multiple tasks match due to aliases, a TaskNameConflictError is returned.

func (*Executor) GetHash 

func (e *Executor) GetHash(t *ast.Task) (string, error)

func (*Executor) GetTask 

func (e *Executor) GetTask(call *Call) (*ast.Task, error)

GetTask will return the task with the name matching the given call from the taskfile. If no task is found, it will search for tasks with a matching alias. If multiple tasks contain the same alias or no matches are found an error is returned.

func (*Executor) GetTaskList 

func (e *Executor) GetTaskList(filters ...FilterFunc) ([]*ast.Task, error)

func (*Executor) InterceptInterruptSignals 

func (e *Executor) InterceptInterruptSignals()

NOTE(@andreynering): This function intercepts SIGINT and SIGTERM signals so the Task process is not killed immediately and processes running have time to do cleanup work.

func (*Executor) ListTaskNames 

func (e *Executor) ListTaskNames(allTasks bool) error

ListTaskNames prints only the task names in a Taskfile. Only tasks with a non-empty description are printed if allTasks is false. Otherwise, all task names are printed.

func (*Executor) ListTasks 

func (e *Executor) ListTasks(o ListOptions) (bool, error)

ListTasks prints a list of tasks. Tasks that match the given filters will be excluded from the list. The function returns a boolean indicating whether tasks were found and an error if one was encountered while preparing the output.

func (*Executor) Options 

func (e *Executor) Options(opts ...ExecutorOption)

Options loops through the given ExecutorOption functions and applies them to the Executor.

func (*Executor) Run 

func (e *Executor) Run(ctx context.Context, calls ...*Call) error

Run runs Task

func (*Executor) RunTask 

func (e *Executor) RunTask(ctx context.Context, call *Call) error

RunTask runs a task by its name

func (*Executor) Setup 

func (e *Executor) Setup() error

func (*Executor) Status 

func (e *Executor) Status(ctx context.Context, calls ...*Call) error

Status returns an error if any the of given tasks is not up-to-date

func (*Executor) ToEditorOutput 

func (e *Executor) ToEditorOutput(tasks []*ast.Task, noStatus bool, nested bool) (*editors.Namespace, error)

type ExecutorOption 

type ExecutorOption interface {
	ApplyToExecutor(*Executor)
}

An ExecutorOption is any type that can apply a configuration to an Executor.

func WithAssumeTerm 

func WithAssumeTerm(assumeTerm bool) ExecutorOption

WithAssumeTerm is used for testing purposes to simulate a terminal.

func WithAssumeYes 

func WithAssumeYes(assumeYes bool) ExecutorOption

WithAssumeYes tells the Executor to assume "yes" for all prompts.

func WithCACert 

func WithCACert(caCert string) ExecutorOption

WithCACert sets the path to a custom CA certificate for TLS connections.

func WithCacheExpiryDuration 

func WithCacheExpiryDuration(duration time.Duration) ExecutorOption

WithCacheExpiryDuration sets the duration after which the cache is considered expired. By default, the cache is 0 (disabled).

func WithCert 

func WithCert(cert string) ExecutorOption

WithCert sets the path to a client certificate for TLS connections.

func WithCertKey 

func WithCertKey(certKey string) ExecutorOption

WithCertKey sets the path to a client certificate key for TLS connections.

func WithColor 

func WithColor(color bool) ExecutorOption

WithColor tells the Executor whether or not to output using colorized strings.

func WithConcurrency 

func WithConcurrency(concurrency int) ExecutorOption

WithConcurrency sets the maximum number of tasks that the Executor can run in parallel.

func WithDir 

func WithDir(dir string) ExecutorOption

WithDir sets the working directory of the Executor. By default, the directory is set to the user's current working directory.

func WithDisableFuzzy 

func WithDisableFuzzy(disableFuzzy bool) ExecutorOption

WithDisableFuzzy tells the Executor to disable fuzzy matching for task names.

func WithDownload 

func WithDownload(download bool) ExecutorOption

WithDownload forces the Executor to download a fresh copy of the taskfile from the remote source.

func WithDry 

func WithDry(dry bool) ExecutorOption

WithDry tells the Executor to output the commands that would be run without actually running them.

func WithEntrypoint 

func WithEntrypoint(entrypoint string) ExecutorOption

WithEntrypoint sets the entrypoint (main Taskfile) of the Executor. By default, Task will search for one of the default Taskfiles in the given directory.

func WithFailfast 

func WithFailfast(failfast bool) ExecutorOption

WithFailfast tells the Executor whether or not to check the version of

func WithForce 

func WithForce(force bool) ExecutorOption

WithForce ensures that the Executor always runs a task, even when fingerprinting or prompts would normally stop it.

func WithForceAll 

func WithForceAll(forceAll bool) ExecutorOption

WithForceAll ensures that the Executor always runs all tasks (including subtasks), even when fingerprinting or prompts would normally stop them.

func WithIO 

func WithIO(rw io.ReadWriter) ExecutorOption

WithIO sets the Executor's standard input, output, and error to the same io.ReadWriter.

func WithInsecure 

func WithInsecure(insecure bool) ExecutorOption

WithInsecure allows the Executor to make insecure connections when reading remote taskfiles. By default, insecure connections are rejected.

func WithInteractive 

func WithInteractive(interactive bool) ExecutorOption

WithInteractive tells the Executor to prompt for missing required variables.

func WithInterval 

func WithInterval(interval time.Duration) ExecutorOption

WithInterval sets the interval at which the Executor will wait for duplicated events before running a task.

func WithOffline 

func WithOffline(offline bool) ExecutorOption

WithOffline stops the Executor from being able to make network connections. It will still be able to read local files and cached copies of remote files.

func WithOutputStyle 

func WithOutputStyle(outputStyle ast.Output) ExecutorOption

WithOutputStyle sets the output style of the Executor. By default, the output style is set to the style defined in the Taskfile.

func WithParallel 

func WithParallel(parallel bool) ExecutorOption

WithParallel tells the Executor to run tasks given in the same call in parallel.

func WithRemoteCacheDir 

func WithRemoteCacheDir(dir string) ExecutorOption

WithRemoteCacheDir sets the directory where remote taskfiles are cached.

func WithSilent 

func WithSilent(silent bool) ExecutorOption

WithSilent tells the Executor to suppress all output except for the output of the tasks that are run.

func WithStderr 

func WithStderr(stderr io.Writer) ExecutorOption

WithStderr sets the Executor's standard error io.Writer.

func WithStdin 

func WithStdin(stdin io.Reader) ExecutorOption

WithStdin sets the Executor's standard input io.Reader.

func WithStdout 

func WithStdout(stdout io.Writer) ExecutorOption

WithStdout sets the Executor's standard output io.Writer.

func WithSummary 

func WithSummary(summary bool) ExecutorOption

WithSummary tells the Executor to output a summary of the given tasks instead of running them.

func WithTaskSorter 

func WithTaskSorter(sorter sort.Sorter) ExecutorOption

WithTaskSorter sets the sorter that the Executor will use to sort tasks. By default, the sorter is set to sort tasks alphabetically, but with tasks with no namespace (in the root Taskfile) first.

func WithTempDir 

func WithTempDir(tempDir TempDir) ExecutorOption

WithTempDir sets the temporary directory that will be used by Executor for storing temporary files like checksums and cached remote files. By default, the temporary directory is set to the user's temporary directory.

func WithTimeout 

func WithTimeout(timeout time.Duration) ExecutorOption

WithTimeout sets the Executor's timeout for fetching remote taskfiles. By default, the timeout is set to 10 seconds.

func WithTrustedHosts 

func WithTrustedHosts(trustedHosts []string) ExecutorOption

WithTrustedHosts configures the Executor with a list of trusted hosts for remote Taskfiles. Hosts in this list will not prompt for user confirmation.

func WithVerbose 

func WithVerbose(verbose bool) ExecutorOption

WithVerbose tells the Executor to output more information about the tasks that are run.

func WithVersionCheck 

func WithVersionCheck(enableVersionCheck bool) ExecutorOption

WithVersionCheck tells the Executor whether or not to check the version of

func WithWatch 

func WithWatch(watch bool) ExecutorOption

WithWatch tells the Executor to keep running in the background and watch for changes to the fingerprint of the tasks that are run. When changes are detected, a new task run is triggered.

type FilterFunc 

type FilterFunc func(task *ast.Task) bool

type ListOptions 

type ListOptions struct {
	ListOnlyTasksWithDescriptions bool
	ListAllTasks                  bool
	FormatTaskListAsJSON          bool
	NoStatus                      bool
	Nested                        bool
}

ListOptions collects list-related options

func NewListOptions 

func NewListOptions(list, listAll, listAsJson, noStatus, nested bool) ListOptions

NewListOptions creates a new ListOptions instance

func (ListOptions) Filters 

func (o ListOptions) Filters() []FilterFunc

Filters returns the slice of FilterFunc which filters a list of ast.Task according to the given ListOptions

func (ListOptions) ShouldListTasks 

func (o ListOptions) ShouldListTasks() bool

ShouldListTasks returns true if one of the options to list tasks has been set to true

type MatchingTask 

type MatchingTask struct {
	Task      *ast.Task
	Wildcards []string
}

MatchingTask represents a task that matches a given call. It includes the task itself and a list of wildcards that were matched.

type TempDir 

type TempDir struct {
	Remote      string
	Fingerprint string
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
release command
rite command
sleepit command
internal
deepcopy
editors
env
execext
filepathext
fingerprint
flags
fsext
fsnotifyext
goext
hash
input
logger
output
slicesext
sort
summary
sysinfo
templater
term
version
ast
ast

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.