Document and list aliases on help --names

Author: José Valim

lib/mix/lib/mix.ex

@@ -1,14 +1,148 @@
 defmodule Mix do
-  @moduledoc """
-  Mix is a build tool that provides tasks for creating, compiling and
-  testing Elixir projects. Mix is inspired by the Leiningen
-  build tool for Clojure and was written by one of its contributors.
+  @moduledoc ~S"""
+  Mix is a build tool that provides tasks for creating, compiling,
+  testing Elixir projects, as well as handle dependencies, and more.
 
-  This module works as a facade for accessing the most common functionality
-  in Elixir, such as the shell and the current project configuration.
+  ## Mix.Project
 
-  For getting started with Elixir, checkout out the guide available on
-  [Elixir's website](http://elixir-lang.org).
+  The foundation of Mix is a project. A project can be defined by
+  by using the `Mix.Project` in a module, usually place in a file
+  named `mix.exs`:
+
+      defmodule MyApp.Mixfile do
+        def project do
+          [app: :my_app,
+           version: "1.0.0"]
+        end
+      end
+
+  The `project/0` function is where the project information is defined
+  and it allows developers to configure many tasks.
+
+  After the project above is defined, there are many tasks one can
+  run directly from the command line:
+
+    * `mix compile` - compiles the current project
+    * `mix test` - runs tests for the given project
+    * `mix run` - runs a particular command inside the project
+
+  Each task has its own options and sometimes specific configuration
+  to be defined in the `project/0` function. You can use `mix help`
+  to list all available tasks and `mix help NAME` to show help for
+  a particular task.
+
+  The best way to get started with your first project is by calling
+  `mix new my_project` from the command line.
+
+  ## Mix.Task
+
+  Tasks are what make Mix extensible.
+
+  Any project can extend Mix behaviour by adding their own tasks. For
+  example, you can add the task below inside your project and it will
+  be available to everyone that uses your project:
+
+      defmodule Mix.Tasks.Hello do
+        use Mix.Task
+
+        def run(_) do
+          Mix.shell.info "hello"
+        end
+      end
+
+  Now they can invoke it with `mix run hello`.
+
+  ## Dependencies
+
+  Another important feature in Mix is that it is able to manage your
+  dependencies and integrates nicely with [the Hex package manager](http://hex.pm).
+
+  In order to use dependencies, you just need to add a `:deps` key
+  to your project configuration. We often extract the dependencies
+  listing to its own functions:
+
+      defmodule MyApp.Mixfile do
+        def project do
+          [app: :my_app,
+           version: "1.0.0",
+           deps: deps]
+        end
+
+        defp deps do
+          [{:ecto, "~> 0.3.0"},
+           {:plug, github: "elixir-lang/plug"}]
+        end
+      end
+
+  You can run `mix help deps` to learn more about dependencies in Mix.
+
+  ## Environments
+
+  Mix provides environments.
+
+  Environments allow developers to prepare and organize their project
+  specific to different scenarios. By default, Mix provides three
+  environments:
+
+    * `:dev` - the default environment
+    * `:test` - the environment `mix test` runs on
+    * `:prod` - the environment your dependencies runs on
+
+  The environment can be changed via the command line by setting
+  the `MIX_ENV` environment variable, for example:
+
+      $ MIX_ENV=prod mix run server.exs
+
+  ## Aliases
+
+  Aliases are shortcut or tasks specific to the current project.
+
+  In the `Mix.Task` section, we have defined a task that would be
+  available to everyone using our project as a dependency. What if
+  we wanted the task to only be available for our project? Just
+  define an alias:
+
+      defmodule MyApp.Mixfile do
+        def project do
+          [app: :my_app,
+           version: "1.0.0",
+           aliases: aliases]
+        end
+
+        defp aliases do
+          [c: "compile",
+           hello: &hello/1]
+        end
+
+        defp hello(_) do
+          Mix.shell.info "Hello world"
+        end
+      end
+
+  In the example above, we have defined two aliases. One is `mix c`
+  which is a shortcut for `mix compile`. The other is named
+  `mix hello`, which is the equivalent to the `Mix.Tasks.Hello`
+  we have defined in the `Mix.Task` section.
+
+  Aliases may also be a list, specifying multiple tasks to run
+  at once:
+
+      [all: [&hello/1, "deps.get --only #{Mix.env}", "compile"]]
+
+  In the example above, we have defined an alias named `mix all`,
+  that prints hello, then fetches dependencies specific to the
+  current environment and compiles it.
+
+  Finally, aliases can also be use to augment existing tasks.
+  Let's suppose you want to augment `mix clean` to clean another
+  directory Mix does not know about:
+
+      [clean: ["clean", &clean_extra/1]]
+
+  Where `&clean_extra/1` would be a function in your `mix.exs`
+  with extra clean up logic.
+
+  Note aliases do not show up on `mix help`.
   """
 
   use Application

lib/mix/lib/mix/project.ex

@@ -21,7 +21,7 @@ defmodule Mix.Project do
   even without a project.
 
   In case the developer needs a project or wants to access a special
-  function in the project, he/she can call `Mix.Project.get!/0`
+  function in the project, the developer can call `Mix.Project.get!/0`
   which fails with `Mix.NoProjectError` in case a project is not
   defined.
   """

lib/mix/lib/mix/task.ex

@@ -13,7 +13,7 @@ defmodule Mix.Task do
         use Mix.Task
 
         def run(_) do
-          IO.puts "hello"
+          Mix.shell.info "hello"
         end
       end
 
@@ -194,11 +194,15 @@ defmodule Mix.Task do
   If the task was not yet invoked, it runs the task and
   returns the result.
 
-  If the task was already invoked, it does not run the task
-  again and simply aborts with `:noop`.
+  If there is an alias with the same name, the alias
+  will be invoked instead of a task.
 
-  It may raise an exception if the task was not found
-  or it is invalid. Check `get!/1` for more information.
+  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 the an alias or a task can't
+  be found or the task is invalid. Check `get!/1` for more
+  information.
   """
   @spec run(task_name, [any]) :: any
   def run(task, args \\ []) when is_binary(task) or is_atom(task) do

lib/mix/lib/mix/tasks/help.ex

@@ -9,8 +9,9 @@ defmodule Mix.Tasks.Help do
   ## Arguments
 
       mix help         - prints all tasks and their shortdoc
-      mix help --names - prints all task names
       mix help TASK    - prints full docs for the given task
+      mix help --names - prints all task names and aliases
+                         (useful for autocompleting)
 
   ## Colors
 
@@ -58,8 +59,17 @@ defmodule Mix.Tasks.Help do
   end
 
   def run(["--names"]) do
-    for module <- Enum.sort(Mix.Task.load_all()) do
-      Mix.shell.info "#{Mix.Task.task_name(module)}"
+    tasks =
+      Mix.Task.load_all()
+      |> Enum.map(&Mix.Task.task_name/1)
+
+    aliases =
+      Mix.Project.config[:aliases]
+      |> Dict.keys
+      |> Enum.map(&Atom.to_string/1)
+
+    for info <- Enum.sort(aliases ++ tasks) do
+      Mix.shell.info info
     end
   end
 

lib/mix/test/mix/aliases_test.exs

@@ -8,6 +8,7 @@ defmodule Mix.AliasesTest do
       [aliases: [h: "hello",
                  p: &inspect/1,
                  compile: "hello",
+                 help: ["help", "hello"],
                  "nested.h": [&Mix.shell.info(inspect(&1)), "h foo bar"]]]
     end
   end
@@ -44,4 +45,9 @@ defmodule Mix.AliasesTest do
     assert Mix.Task.run("compile", []) == "Hello, World!"
     assert Mix.Task.run("compile", []) == :noop
   end
+
+  test "run alias override with recursion" do
+    assert Mix.Task.run("help", []) == "Hello, World!"
+    assert_received {:mix_shell, :info, ["mix test" <> _]}
+  end
 end

lib/mix/test/mix/tasks/help_test.exs

@@ -24,10 +24,21 @@ defmodule Mix.Tasks.HelpTest do
     end
   end
 
+
+  defmodule Aliases do
+    def project do
+      [aliases: [h: "hello", c: "compile"]]
+    end
+  end
+
   test "help --names" do
+    Mix.Project.push Aliases
+
     in_fixture "no_mixfile", fn ->
       Mix.Tasks.Help.run ["--names"]
+      assert_received {:mix_shell, :info, ["c"]}
       assert_received {:mix_shell, :info, ["compile"]}
+      assert_received {:mix_shell, :info, ["h"]}
       assert_received {:mix_shell, :info, ["help"]}
       assert_received {:mix_shell, :info, ["escriptize"]}
     end