From 888f36aebb6defd7b903cb24663e65b93109fea1 Mon Sep 17 00:00:00 2001
From: Alisdair McDiarmid <alisdair@users.noreply.github.com>
Date: Tue, 2 Feb 2021 13:09:30 -0500
Subject: [PATCH] cli: Remove positional plan argument from graph

To make the command arguments easier to understand and extend, we are
moving away from positional arguments. This commit changes the graph
command to take a `-plan` flag instead of an optional trailing path.
---
 command/graph.go                        | 15 +++++++--------
 command/graph_test.go                   |  2 +-
 website/docs/cli/commands/graph.html.md | 11 +++++++----
 3 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/command/graph.go b/command/graph.go
index 2267c891f..dfc1a2f8e 100644
--- a/command/graph.go
+++ b/command/graph.go
@@ -23,6 +23,7 @@ func (c *GraphCommand) Run(args []string) int {
 	var graphTypeStr string
 	var moduleDepth int
 	var verbose bool
+	var planPath string
 
 	args = c.Meta.process(args)
 	cmdFlags := c.Meta.defaultFlagSet("graph")
@@ -30,19 +31,14 @@ func (c *GraphCommand) Run(args []string) int {
 	cmdFlags.StringVar(&graphTypeStr, "type", "", "type")
 	cmdFlags.IntVar(&moduleDepth, "module-depth", -1, "module-depth")
 	cmdFlags.BoolVar(&verbose, "verbose", false, "verbose")
+	cmdFlags.StringVar(&planPath, "plan", "", "plan")
 	cmdFlags.Usage = func() { c.Ui.Error(c.Help()) }
 	if err := cmdFlags.Parse(args); err != nil {
 		c.Ui.Error(fmt.Sprintf("Error parsing command-line flags: %s\n", err.Error()))
 		return 1
 	}
 
-	args = cmdFlags.Args()
-	var planPath string
-	if len(args) > 0 {
-		planPath = args[0]
-		args = args[1:]
-	}
-	configPath, err := ModulePath(args)
+	configPath, err := ModulePath(cmdFlags.Args())
 	if err != nil {
 		c.Ui.Error(err.Error())
 		return 1
@@ -170,7 +166,7 @@ func (c *GraphCommand) Help() string {
 Usage: terraform graph [options]
 
   Outputs the visual execution graph of Terraform resources according to
-  configuration files in the current directory.
+  either the current configuration or an execution plan.
 
   The graph is outputted in DOT format. The typical program that can
   read this format is GraphViz, but many web services are also available
@@ -184,6 +180,9 @@ Usage: terraform graph [options]
 
 Options:
 
+  -plan=tfplan     Render graph using the specified plan file instead of the
+                   configuration in the current directory.
+
   -draw-cycles     Highlight any cycles in the graph with colored edges.
                    This helps when diagnosing cycle errors.
 
diff --git a/command/graph_test.go b/command/graph_test.go
index bb474696e..392db1a9c 100644
--- a/command/graph_test.go
+++ b/command/graph_test.go
@@ -150,7 +150,7 @@ func TestGraph_plan(t *testing.T) {
 	}
 
 	args := []string{
-		planPath,
+		"-plan", planPath,
 	}
 	if code := c.Run(args); code != 0 {
 		t.Fatalf("bad: \n%s", ui.ErrorWriter.String())
diff --git a/website/docs/cli/commands/graph.html.md b/website/docs/cli/commands/graph.html.md
index 04c286b03..dea3d441b 100644
--- a/website/docs/cli/commands/graph.html.md
+++ b/website/docs/cli/commands/graph.html.md
@@ -18,14 +18,14 @@ The output is in the DOT format, which can be used by
 
 Usage: `terraform graph [options]`
 
-Outputs the visual dependency graph of Terraform resources represented by the
-configuration in the current working directory.
+Outputs the visual execution graph of Terraform resources according to
+either the current configuration or an execution plan.
 
 The graph is outputted in DOT format. The typical program that can
 read this format is GraphViz, but many web services are also available
 to read this format.
 
-The -type flag can be used to control the type of graph shown. Terraform
+The `-type` flag can be used to control the type of graph shown. Terraform
 creates different graphs for different operations. See the options below
 for the list of types supported. The default type is "plan" if a
 configuration is given, and "apply" if a plan file is passed as an
@@ -33,6 +33,9 @@ argument.
 
 Options:
 
+* `-plan=tfplan`    - Render graph using the specified plan file instead of the
+                      configuration in the current directory.
+
 * `-draw-cycles`    - Highlight any cycles in the graph with colored edges.
                       This helps when diagnosing cycle errors.
 
@@ -48,7 +51,7 @@ The output of `terraform graph` is in the DOT format, which can
 easily be converted to an image by making use of `dot` provided
 by GraphViz:
 
-```shell
+```shellsession
 $ terraform graph | dot -Tsvg > graph.svg
 ```