main: Various minor tweaks to our main help output

[apparentlymart]

This is very much a case of my having an extra little bit of time at the end of my week and so using it to tackle a relatively-minor thing that's been kinda bothering me for a while...

This set of commits makes an assortment of different adjustments to code that contributes to the help output that Terraform prints when you just run terraform with no other arguments, aiming to make it more useful to folks who are just getting started, slightly more compact in general, and more consistent in its writing style.

The sum of all of this is the following output:

Usage: terraform [global options] <subcommand> [args]

The available commands for execution are listed below.
The primary workflow commands are given first, followed by
less common or more advanced commands.

Main commands:
  init          Prepare your working directory for other commands
  validate      Check whether the configuration is valid
  plan          Show changes required by the current configuration
  apply         Create or update infrastructure
  destroy       Destroy previously-created infrastructure

All other commands:
  console       Try Terraform expressions at an interactive command prompt
  fmt           Reformat your configuration in the standard style
  force-unlock  Release a stuck lock on the current workspace
  get           Install or upgrade remote Terraform modules
  graph         Generate a Graphviz graph of the steps in an operation
  import        Associate existing infrastructure with a Terraform resource
  login         Obtain and save credentials for a remote host
  logout        Remove locally-stored credentials for a remote host
  output        Show output values from your root module
  providers     Show the providers required for this configuration
  refresh       Update the state to match remote systems
  show          Show the current state or a saved plan
  state         Advanced state management
  taint         Mark a resource instance as not fully functional
  untaint       Remove the 'tainted' state from a resource instance
  version       Show the current Terraform version
  workspace     Workspace management

Global options (use these before the subcommand, if any):
  -chdir=DIR    Switch to a different working directory before executing the
                given subcommand.
  -help         Show this help output, or the help for a specified subcommand.
  -version      An alias for the "version" subcommand.

Some highlights here are:

• The main workflow commands have greater prominence by separating them from everything else. I chose these as the commands that Terraform users will use routinely as part of their main workflow, whereas the other commands are ones that you're more likely to interact with only if you learn about them from elsewhere as part of dealing with some unusual situation or special use-case.
• A few more "useless" commands are hidden, where that's defined as commands that exist only to tell a user something is no longer supported, to alias something for backward compatibility, or as an internal implementation detail.
• The command short descriptions are all written in the imperative mood, except the ones that are just containers for some other nested commands.
• The weird debug command, which previously did nothing except claim to be a container command even though it had no nested commands, is now removed entirely.

[codecov]

Codecov Report

Merging #26695 into master will increase coverage by 0.00%.
The diff coverage is 16.30%.

Impacted Files	Coverage Δ
command/apply.go	42.38% <0.00%> (-0.21%)	⬇️
command/console.go	37.25% <0.00%> (ø)
command/fmt.go	76.38% <0.00%> (ø)
command/get.go	40.00% <0.00%> (-3.25%)	⬇️
command/graph.go	43.75% <0.00%> (ø)
command/import.go	53.53% <0.00%> (ø)
command/init.go	62.72% <0.00%> (ø)
command/output.go	71.85% <0.00%> (ø)
command/plan.go	41.95% <0.00%> (ø)
command/providers.go	52.43% <0.00%> (ø)
... and 15 more

[pselle]

Thank you for picking this up!! Is this a candidate for 0.14 as well? The help there still shows 0.12upgrade etc under "All other commands" and it bothers me and I like that with this it's gone!

[pselle]

Note: Since you remove the debug command, that's technically a breaking change, to consider when considering this for yea/nay on 0.14. You could perhaps separate that change out and keep the rest, to make things backport-able.

[apparentlymart]

I had not been planning on backporting this to 0.14; my motivation here was more of a "general clean up on the way to 1.0" sort of thing, and so I don't feel much urgency about it. The various oddities have been there for several years so I feel like a few more months won't hurt. I could probably be persuaded otherwise, though. 😀

While you're right that removing the debug command is technically a breaking change, I don't think it's a breaking change in any useful way because all the terraform debug command used to do was print out help text telling you that it had zero subcommands. 🙃 So I'd be inclined to backport it anyway, if we decide to go that way, but I'd also be okay with carving just that part out of the backport; it's already a separate commit in this patch set anyway, so not too hard to skip.

[ghost]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.