Provides conveniences for creating, loading, and manipulating Mix tasks.

To create a new Mix task, you'll need to:

1. Create a module whose name begins with Mix.Tasks. (for example, Mix.Tasks.MyTask).
2. Call use Mix.Task in that module.
3. Implement the Mix.Task behaviour in that module (that is, implement the run/1 callback).

Typically, task modules live inside the lib/mix/tasks/ directory, and their file names use dot separators instead of underscores (for example, deps.clean.ex) - although ultimately the file name is not relevant.

For example:

# lib/mix/tasks/echo.ex
defmodule Mix.Tasks.Echo do
  @moduledoc "Printed when the user requests `mix help echo`"
  @shortdoc "Echoes arguments"

  use Mix.Task

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

The command name will correspond to the portion of the module name following Mix.Tasks.. For example, a module name of Mix.Tasks.Deps.Clean corresponds to a task name of deps.clean.

The run/1 function will receive a list of all command line arguments passed, according to the user's terminal.

For example, if the args in the above echo task were inspected, you might see something like this:

$ mix echo 'A and B' C --test
["A and B", "C", "--test"]

use Mix.Task

When you use Mix.Task, the Mix.Task module will set @behaviour Mix.Task and define default values for the module attributes documented in the section below.

Module attributes

You can control some behavior of your Mix task by setting module attributes. This section documents the available attributes.

@shortdoc

Define the @shortdoc attribute if you wish to make the task publicly visible on mix help. Omit this attribute if you do not want your task to be listed via mix help.

@moduledoc

The @moduledoc attribute may override @shortdoc. The task will not appear in mix help if documentation for the entire module is hidden with @moduledoc false.

@requirements

If a task has requirements, they can be listed using the @requirements attribute. Requirements are other Mix tasks that this task requires to have run. For example:

@requirements ["app.config"]

A task will typically depend on one of the following tasks:

• "loadpaths" - this ensures dependencies are available and compiled. If you are publishing a task as part of a library to be used by others, and your task does not need to interact with the user code in any way, this is the recommended requirement

• "app.config" - additionally compiles and load the runtime configuration for the current project. If you are creating a task to be used within your application or as part of a library, which must invoke or interact with the user code, this is the minimum recommended requirement

• "app.start" - additionally starts the supervision tree of the current project and its dependencies

@recursive

Set @recursive true if you want the task to run on each umbrella child in an umbrella project.

@preferred_cli_env

Sets the preferred Mix environment for this task. For example, if your task is meant to be used for testing, you could set

@preferred_cli_env :test

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.