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"]

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.