Support --output in mix deps.tree and mix app.tree, closes #15288

Author: josevalim

lib/mix/lib/mix/tasks/app.tree.ex

@@ -30,8 +30,20 @@ defmodule Mix.Tasks.App.Tree do
         This is the default on Windows.
 
       * `dot` - produces a DOT graph description of the application tree
-        in `app_tree.dot` in the current directory.
-        Warning: this will overwrite any previously generated file.
+        in `app_tree.dot` in the current directory. See the documentation
+        for the `--output` option to learn how to control where the file
+        is written and other related details.
+
+    * `--output` *(since v1.20.0)* - can be used to override the location of
+      the file created by the `dot` format. It can be set to
+
+      * `-` - prints the output to standard output;
+
+      * a path - writes the output graph to the given path
+
+      If the output file already exists then it will be renamed in place
+      to have a `.bak` suffix, possibly overwriting any existing `.bak` file.
+      If this rename fails a fatal exception will be thrown.
 
   """
 
@@ -42,7 +54,9 @@ defmodule Mix.Tasks.App.Tree do
     Mix.Task.run("compile", args)
 
     {app, opts} =
-      case OptionParser.parse!(args, strict: [exclude: :keep, format: :string]) do
+      case OptionParser.parse!(args,
+             strict: [exclude: :keep, format: :string, output: :string]
+           ) do
         {opts, []} ->
           app =
             Mix.Project.config()[:app] ||
@@ -67,17 +81,23 @@ defmodule Mix.Tasks.App.Tree do
 
     if opts[:format] == "dot" do
       root = [{app, :normal}]
-      Mix.Utils.write_dot_graph!("app_tree.dot", "application tree", root, callback, opts)
 
-      """
-      Generated "app_tree.dot" in the current directory. To generate a PNG:
+      file_spec =
+        Mix.Utils.write_dot_graph!("app_tree.dot", "application tree", root, callback, opts)
 
-         dot -Tpng app_tree.dot -o app_tree.png
+      if file_spec != "-" do
+        png_file_spec = (file_spec |> Path.rootname() |> Path.basename()) <> ".png"
 
-      For more options see https://www.graphviz.org/.
-      """
-      |> String.trim_trailing()
-      |> Mix.shell().info()
+        """
+        Generated "#{Path.relative_to_cwd(file_spec)}". To generate a PNG:
+
+           dot -Tpng #{inspect(file_spec)} -o #{inspect(png_file_spec)}
+
+        For more options see https://www.graphviz.org/.
+        """
+        |> String.trim_trailing()
+        |> Mix.shell().info()
+      end
     else
       Mix.Utils.print_tree([{app, :normal}], callback, opts)
     end

lib/mix/lib/mix/tasks/deps.tree.ex

@@ -37,8 +37,20 @@ defmodule Mix.Tasks.Deps.Tree do
         This is the default on Windows.
 
       * `dot` - produces a DOT graph description of the dependency tree
-        in `deps_tree.dot` in the current directory.
-        Warning: this will override any previously generated file.
+        in `deps_tree.dot` in the current directory. See the documentation
+        for the `--output` option to learn how to control where the file
+        is written and other related details.
+
+    * `--output` *(since v1.20.0)* - can be used to override the location of
+      the file created by the `dot` format. It can be set to
+
+      * `-` - prints the output to standard output;
+
+      * a path - writes the output graph to the given path
+
+      If the output file already exists then it will be renamed in place
+      to have a `.bak` suffix, possibly overwriting any existing `.bak` file.
+      If this rename fails a fatal exception will be thrown.
 
   ## Examples
 
@@ -61,7 +73,8 @@ defmodule Mix.Tasks.Deps.Tree do
     target: :string,
     exclude: :keep,
     umbrella_only: :boolean,
-    format: :string
+    format: :string,
+    output: :string
   ]
 
   @impl true
@@ -89,17 +102,23 @@ defmodule Mix.Tasks.Deps.Tree do
 
     if opts[:format] == "dot" do
       callback = callback(&format_dot/1, deps, opts)
-      Mix.Utils.write_dot_graph!("deps_tree.dot", "dependency tree", [root], callback, opts)
 
-      """
-      Generated "deps_tree.dot" in the current directory. To generate a PNG:
+      file_spec =
+        Mix.Utils.write_dot_graph!("deps_tree.dot", "dependency tree", [root], callback, opts)
 
-          dot -Tpng deps_tree.dot -o deps_tree.png
+      if file_spec != "-" do
+        png_file_spec = (file_spec |> Path.rootname() |> Path.basename()) <> ".png"
 
-      For more options see https://www.graphviz.org/.
-      """
-      |> String.trim_trailing()
-      |> Mix.shell().info()
+        """
+        Generated "#{Path.relative_to_cwd(file_spec)}". To generate a PNG:
+
+            dot -Tpng #{inspect(file_spec)} -o #{inspect(png_file_spec)}
+
+        For more options see https://www.graphviz.org/.
+        """
+        |> String.trim_trailing()
+        |> Mix.shell().info()
+      end
     else
       callback = callback(&format_tree/1, deps, opts)
       Mix.Utils.print_tree([root], callback, opts)

lib/mix/test/mix/tasks/app.tree_test.exs

@@ -7,6 +7,8 @@ Code.require_file("../../test_helper.exs", __DIR__)
 defmodule Mix.Tasks.App.TreeTest do
   use MixTest.Case
 
+  import ExUnit.CaptureIO
+
   defmodule AppDepsSample do
     def project do
       [app: :test, version: "0.1.0"]
@@ -137,6 +139,54 @@ defmodule Mix.Tasks.App.TreeTest do
     end)
   end
 
+  @expected_dot """
+  digraph "application tree" {
+    "test"
+    "test" -> "app_deps_sample"
+    "app_deps_sample" -> "app_deps2_sample"
+    "app_deps2_sample" -> "app_deps4_sample" [label="(included)"]
+    "app_deps_sample" -> "app_deps3_sample"
+    "test" -> "elixir"
+    "test" -> "logger"
+    "logger" -> "elixir"
+  }
+  """
+
+  @tag apps: [:test, :app_deps_sample, :app_deps2_sample, :app_deps3_sample, :app_deps4_sample]
+  test "writes the dot graph to a custom file via --output", context do
+    in_tmp(context.test, fn ->
+      Mix.Project.push(AppDepsSample)
+
+      load_apps()
+      Mix.Tasks.App.Tree.run(["--format", "dot", "--output", "custom.dot"])
+
+      assert File.read!("custom.dot") == @expected_dot
+      refute File.exists?("app_tree.dot")
+
+      File.write!("custom.dot", "previous")
+      Mix.Tasks.App.Tree.run(["--format", "dot", "--output", "custom.dot"])
+      assert File.read!("custom.dot") == @expected_dot
+      assert File.read!("custom.dot.bak") == "previous"
+    end)
+  end
+
+  @tag apps: [:test, :app_deps_sample, :app_deps2_sample, :app_deps3_sample, :app_deps4_sample]
+  test "writes the dot graph to stdout via --output -", context do
+    in_tmp(context.test, fn ->
+      Mix.Project.push(AppDepsSample)
+
+      load_apps()
+
+      output =
+        capture_io(fn ->
+          Mix.Tasks.App.Tree.run(["--format", "dot", "--output", "-"])
+        end)
+
+      assert output == @expected_dot
+      refute File.exists?("app_tree.dot")
+    end)
+  end
+
   defp load_apps(optional_apps \\ []) do
     :ok = :application.load({:application, :app_deps4_sample, [vsn: ~c"1.0.0", env: []]})
     :ok = :application.load({:application, :app_deps3_sample, [vsn: ~c"1.0.0", env: []]})

lib/mix/test/mix/tasks/deps.tree_test.exs

@@ -7,6 +7,8 @@ Code.require_file("../../test_helper.exs", __DIR__)
 defmodule Mix.Tasks.Deps.TreeTest do
   use MixTest.Case
 
+  import ExUnit.CaptureIO
+
   defmodule ConvergedDepsApp do
     def project do
       [
@@ -164,4 +166,45 @@ defmodule Mix.Tasks.Deps.TreeTest do
   after
     purge([DepsOnGitRepo.MixProject, GitRepo.MixProject])
   end
+
+  @expected_dot """
+  digraph "dependency tree" {
+    "sample"
+    "sample" -> "deps_on_git_repo" [label="0.2.0"]
+    "sample" -> "git_repo" [label=">= 0.1.0"]
+  }
+  """
+
+  test "writes the dot graph to a custom file via --output", context do
+    in_tmp(context.test, fn ->
+      Mix.Project.push(ConvergedDepsApp)
+
+      Mix.Tasks.Deps.Tree.run(["--format", "dot", "--output", "custom.dot"])
+      assert File.read!("custom.dot") == @expected_dot
+      refute File.exists?("deps_tree.dot")
+
+      File.write!("custom.dot", "previous")
+      Mix.Tasks.Deps.Tree.run(["--format", "dot", "--output", "custom.dot"])
+      assert File.read!("custom.dot") == @expected_dot
+      assert File.read!("custom.dot.bak") == "previous"
+    end)
+  after
+    purge([DepsOnGitRepo.MixProject, GitRepo.MixProject])
+  end
+
+  test "writes the dot graph to stdout via --output -", context do
+    in_tmp(context.test, fn ->
+      Mix.Project.push(ConvergedDepsApp)
+
+      output =
+        capture_io(fn ->
+          Mix.Tasks.Deps.Tree.run(["--format", "dot", "--output", "-"])
+        end)
+
+      assert output == @expected_dot
+      refute File.exists?("deps_tree.dot")
+    end)
+  after
+    purge([DepsOnGitRepo.MixProject, GitRepo.MixProject])
+  end
 end