# Mix v1.10.3 Mix.Task behaviour View Source

A simple module that provides conveniences for creating, loading and manipulating tasks.

A Mix task can be defined by simply using `Mix.Task` in a module starting with `Mix.Tasks.` and defining the `run/1` function:

    defmodule Mix.Tasks.Echo do
      use Mix.Task

      @impl Mix.Task
      def run(args) do
        Mix.shell().info(Enum.join(args, " "))
      end
    end

The `run/1` function will receive a list of all arguments passed to the command line.

## Attributes

There are a few attributes available in Mix tasks to configure them in Mix:

- `@shortdoc` - makes the task public with a short description that appears on `mix help`
- `@recursive` - runs the task recursively in umbrella projects
- `@preferred_cli_env` - recommends environment to run task. It is used in absence of a Mix project recommendation, or explicit `MIX_ENV`, and it only works for tasks in the current project. `@preferred_cli_env` is not loaded from dependencies as we need to know the environment before dependencies are loaded.

## Documentation

Users can read the documentation for public Mix tasks by running `mix help my_task`. The documentation that will be shown is the `@moduledoc` of the task's module.

# Link to this section Summary

## Types

task_module()
task_name()

## Functions

alias?(task)

Checks if an alias called `task` exists.

all_modules()

Returns all loaded task modules.

clear()

Clears all invoked tasks, allowing them to be reinvoked.

get(task)

Receives a task name and returns the task module if found.

get!(task)

Receives a task name and retrieves the task module.

load_all()

Loads all tasks in all code paths.

load_tasks(dirs)

Loads all tasks in the given `paths`.

moduledoc(module)

Gets the moduledoc for the given task `module`.

preferred_cli_env(task)

Gets preferred CLI environment for the task.

recursing?()

Indicates if the current task is recursing.

recursive(module)

Checks if the task should be run recursively for all sub-apps in umbrella projects.

reenable(task)

Reenables a given task so it can be executed again down the stack.

rerun(task, args \\ [])

Reruns `task` with the given arguments.

run(task, args \\ [])

Runs a `task` with the given `args`.

shortdoc(module)

Gets the shortdoc for the given task `module`.

task?(module)

Returns `true` if given module is a task.

task_name(module)

Returns the task name for the given `module`.

## Callbacks

run(command_line_args)

A task needs to implement `run` which receives a list of command line args.

# Link to this section Types

Link to this type

# task_module()

View Source

## Specs

    task_module() :: atom()

Link to this type

# task_name()

View Source

## Specs

    task_name() :: String.t() | atom()

# Link to this section Functions

Link to this function

# alias?(task)

View Source

## Specs

    alias?(task_name()) :: boolean()

Checks if an alias called `task` exists.

For more information about task aliasing, take a look at the "Aliasing" section in the docs for `Mix`.

Link to this function

# all_modules()

View Source

## Specs

    all_modules() :: [task_module()]

Returns all loaded task modules.

Modules that are not yet loaded won't show up. Check `load_all/0` if you want to preload all tasks.

Link to this function

# clear()

View Source

## Specs

    clear() :: :ok

Clears all invoked tasks, allowing them to be reinvoked.

This operation is not recursive.

Link to this function

# get(task)

View Source

## Specs

    get(task_name()) :: task_module() | nil

Receives a task name and returns the task module if found.

Otherwise returns `nil` in case the module exists, but it isn't a task or cannot be found.

Link to this function

# get!(task)

View Source

## Specs

    get!(task_name()) :: task_module()

Receives a task name and retrieves the task module.

## Exceptions

- `Mix.NoTaskError` - raised if the task could not be found
- `Mix.InvalidTaskError` - raised if the task is not a valid `Mix.Task`

Link to this function

# load_all()

View Source

## Specs

    load_all() :: [task_module()]

Loads all tasks in all code paths.

Link to this function

# load_tasks(dirs)

View Source

## Specs

    load_tasks([List.Chars.t()]) :: [task_module()]

Loads all tasks in the given `paths`.

Link to this function

# moduledoc(module)

View Source

## Specs

    moduledoc(task_module()) :: String.t() | nil | false

Gets the moduledoc for the given task `module`.

Returns the moduledoc or `nil`.

Link to this function

# preferred_cli_env(task)

View Source

## Specs

    preferred_cli_env(task_name()) :: atom() | nil

Gets preferred CLI environment for the task.

Returns environment (for example, `:test`, or `:prod`), or `nil`.

Link to this function

# recursing?()

View Source (since 1.8.0)

## Specs

    recursing?() :: boolean()

Indicates if the current task is recursing.

This returns true if a task is marked as recursive and it is being executed inside an umbrella project.

Link to this function

# recursive(module)

View Source

## Specs

    recursive(task_module()) :: boolean()

Checks if the task should be run recursively for all sub-apps in umbrella projects.

Returns `true` or `false`.

Link to this function

# reenable(task)

View Source

## Specs

    reenable(task_name()) :: :ok

Reenables a given task so it can be executed again down the stack.

Both alias and the regular stack are reenabled when this function is called.

If an umbrella project reenables a task, it is reenabled for all child projects.

Link to this function

# rerun(task, args \\ [])

View Source

## Specs

    rerun(task_name(), [any()]) :: any()

Reruns `task` with the given arguments.

This function reruns the given task; to do that, it first re-enables the task and then runs it as normal.

Link to this function

# run(task, args \\ [])

View Source

## Specs

    run(task_name(), [any()]) :: any()

Runs a `task` with the given `args`.

If the task was not yet invoked, it runs the task and returns the result.

If there is an alias with the same name, the alias will be invoked instead of the original task.

If the task or alias were already invoked, it does not run them again and simply aborts with `:noop`.

It may raise an exception if an alias or a task can't be found or the task is invalid. Check `get!/1` for more information.

Link to this function

# shortdoc(module)

View Source

## Specs

    shortdoc(task_module()) :: String.t() | nil

Gets the shortdoc for the given task `module`.

Returns the shortdoc or `nil`.

Link to this function

# task?(module)

View Source

## Specs

    task?(task_module()) :: boolean()

Returns `true` if given module is a task.

Link to this function

# task_name(module)

View Source

## Specs

    task_name(task_module()) :: task_name()

Returns the task name for the given `module`.

# Link to this section Callbacks

Link to this callback

# run(command_line_args)

View Source

## Specs

    run(command_line_args :: [binary()]) :: any()

A task needs to implement `run` which receives a list of command line args.