From 5a57962a3246e8923c2c3d57f245a6bbc3b6f1a5 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Tue, 30 May 2017 17:46:12 -0700 Subject: [PATCH] website: replace "env" command docs with "workspace" command docs We are replacing this terminology. The old command continues to work for compatibility, but is deprecated. The docs should reflect the currently-recommended form. --- .../source/docs/commands/env.html.markdown | 13 +++++ .../source/docs/commands/env/delete.html.md | 39 --------------- .../source/docs/commands/env/index.html.md | 21 -------- website/source/docs/commands/env/list.html.md | 27 ---------- website/source/docs/commands/env/new.html.md | 50 ------------------- .../source/docs/commands/env/select.html.md | 31 ------------ .../source/docs/commands/index.html.markdown | 2 +- .../docs/commands/workspace/delete.html.md | 39 +++++++++++++++ .../docs/commands/workspace/index.html.md | 21 ++++++++ .../docs/commands/workspace/list.html.md | 27 ++++++++++ .../docs/commands/workspace/new.html.md | 49 ++++++++++++++++++ .../docs/commands/workspace/select.html.md | 31 ++++++++++++ website/source/layouts/commands-env.erb | 38 -------------- website/source/layouts/commands-workspace.erb | 38 ++++++++++++++ website/source/layouts/docs.erb | 6 ++- 15 files changed, 224 insertions(+), 208 deletions(-) create mode 100644 website/source/docs/commands/env.html.markdown delete mode 100644 website/source/docs/commands/env/delete.html.md delete mode 100644 website/source/docs/commands/env/index.html.md delete mode 100644 website/source/docs/commands/env/list.html.md delete mode 100644 website/source/docs/commands/env/new.html.md delete mode 100644 website/source/docs/commands/env/select.html.md create mode 100644 website/source/docs/commands/workspace/delete.html.md create mode 100644 website/source/docs/commands/workspace/index.html.md create mode 100644 website/source/docs/commands/workspace/list.html.md create mode 100644 website/source/docs/commands/workspace/new.html.md create mode 100644 website/source/docs/commands/workspace/select.html.md delete mode 100644 website/source/layouts/commands-env.erb create mode 100644 website/source/layouts/commands-workspace.erb diff --git a/website/source/docs/commands/env.html.markdown b/website/source/docs/commands/env.html.markdown new file mode 100644 index 000000000..c19bdeffc --- /dev/null +++ b/website/source/docs/commands/env.html.markdown @@ -0,0 +1,13 @@ +--- +layout: "docs" +page_title: "Command: env" +sidebar_current: "docs-commands-env" +description: |- + The terraform env command is a deprecated, legacy form of "terraform workspace". +--- + +# Command: env + +The `terraform env` command is deprecated. +[The `terraform workspace` command](/docs/commands/workspace/) +should be used instead. diff --git a/website/source/docs/commands/env/delete.html.md b/website/source/docs/commands/env/delete.html.md deleted file mode 100644 index 1a8af4113..000000000 --- a/website/source/docs/commands/env/delete.html.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: "commands-env" -page_title: "Command: env delete" -sidebar_current: "docs-env-sub-delete" -description: |- - The terraform env delete command is used to create a delete state environment. ---- - -# Command: env delete - -The `terraform env delete` command is used to delete an existing environment. - -## Usage - -Usage: `terraform env delete [NAME]` - -This command will delete the specified environment. - -To delete an environment, it must already exist, it must be empty, and -it must not be your current environment. If the environment -is not empty, Terraform will not allow you to delete it without the -`-force` flag. - -If you delete a non-empty state (via force), then resources may become -"dangling". These are resources that Terraform no longer manages since -a state doesn't point to them, but still physically exist. This is sometimes -preferred: you want Terraform to stop managing resources. Most of the time, -however, this is not intended so Terraform protects you from doing this. - -The command-line flags are all optional. The list of available flags are: - -* `-force` - Delete the state even if non-empty. Defaults to false. - -## Example - -``` -$ terraform env delete example -Deleted environment "example"! -``` diff --git a/website/source/docs/commands/env/index.html.md b/website/source/docs/commands/env/index.html.md deleted file mode 100644 index cacf34286..000000000 --- a/website/source/docs/commands/env/index.html.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: "commands-env" -page_title: "Command: env" -sidebar_current: "docs-env-index" -description: |- - The `terraform env` command is used to manage state environments. ---- - -# Env Command - -The `terraform env` command is used to manage -[state environments](/docs/state/environments.html). - -This command is a nested subcommand, meaning that it has further subcommands. -These subcommands are listed to the left. - -## Usage - -Usage: `terraform env [options] [args]` - -Please click a subcommand to the left for more information. diff --git a/website/source/docs/commands/env/list.html.md b/website/source/docs/commands/env/list.html.md deleted file mode 100644 index 97fff3b6b..000000000 --- a/website/source/docs/commands/env/list.html.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: "commands-env" -page_title: "Command: env list" -sidebar_current: "docs-env-sub-list" -description: |- - The terraform env list command is used to list all created state environments. ---- - -# Command: env list - -The `terraform env list` command is used to list all created state environments. - -## Usage - -Usage: `terraform env list` - -The command will list all created environments. The current environment -will have an asterisk (`*`) next to it. - -## Example - -``` -$ terraform env list - default -* development - mitchellh-test -``` diff --git a/website/source/docs/commands/env/new.html.md b/website/source/docs/commands/env/new.html.md deleted file mode 100644 index 57549aa9b..000000000 --- a/website/source/docs/commands/env/new.html.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -layout: "commands-env" -page_title: "Command: env new" -sidebar_current: "docs-env-sub-new" -description: |- - The terraform env new command is used to create a new state environment. ---- - -# Command: env new - -The `terraform env new` command is used to create a new state -environment. - -## Usage - -Usage: `terraform env new [NAME]` - -This command will create a new environment with the given name. This -environment must not already exist. - -If the `-state` flag is given, the state specified by the given path -will be copied to initialize the state for this new environment. - -The command-line flags are all optional. The list of available flags are: - -* `-state=path` - Path to a state file to initialize the state of this environment. - -## Example: Create - -``` -$ terraform env new example -Created and switched to environment "example"! - -You're now on a new, empty environment. Environments isolate their state, -so if you run "terraform plan" Terraform will not see any existing state -for this configuration. -``` - -## Example: Create from State - -To create a new environment from a pre-existing state path: - -``` -$ terraform env new -state=old.terraform.tfstate example -Created and switched to environment "example"! - -You're now on a new, empty environment. Environments isolate their state, -so if you run "terraform plan" Terraform will not see any existing state -for this configuration. -``` diff --git a/website/source/docs/commands/env/select.html.md b/website/source/docs/commands/env/select.html.md deleted file mode 100644 index 480e34454..000000000 --- a/website/source/docs/commands/env/select.html.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: "commands-env" -page_title: "Command: env select" -sidebar_current: "docs-env-sub-select" -description: |- - The terraform env select command is used to select state environments. ---- - -# Command: env select - -The `terraform env select` command is used to select to a different -environment that is already created. - -## Usage - -Usage: `terraform env select [NAME]` - -This command will select to another environment. The environment must -already be created. - -## Example - -``` -$ terraform env list - default -* development - mitchellh-test - -$ terraform env select default -Switched to environment "default"! -``` diff --git a/website/source/docs/commands/index.html.markdown b/website/source/docs/commands/index.html.markdown index d48fcb1e6..27ee37fb3 100644 --- a/website/source/docs/commands/index.html.markdown +++ b/website/source/docs/commands/index.html.markdown @@ -33,7 +33,6 @@ Common commands: apply Builds or changes infrastructure console Interactive console for Terraform interpolations destroy Destroy Terraform-managed infrastructure - env Environment management fmt Rewrites config files to canonical format get Download and install modules for the configuration graph Create a visual graph of Terraform resources @@ -49,6 +48,7 @@ Common commands: untaint Manually unmark a resource as tainted validate Validates the Terraform files version Prints the Terraform version + workspace Workspace management All other commands: debug Debug output management (experimental) diff --git a/website/source/docs/commands/workspace/delete.html.md b/website/source/docs/commands/workspace/delete.html.md new file mode 100644 index 000000000..f3549365b --- /dev/null +++ b/website/source/docs/commands/workspace/delete.html.md @@ -0,0 +1,39 @@ +--- +layout: "commands-workspace" +page_title: "Command: workspace delete" +sidebar_current: "docs-workspace-sub-delete" +description: |- + The terraform workspace delete command is used to delete a workspace. +--- + +# Command: workspace delete + +The `terraform workspace delete` command is used to delete an existing workspace. + +## Usage + +Usage: `terraform workspace delete [NAME]` + +This command will delete the specified workspace. + +To delete an workspace, it must already exist, it must have an empty state, +and it must not be your current workspace. If the workspace state is not empty, +Terraform will not allow you to delete it unless the `-force` flag is specified. + +If you delete a workspace with a non-empty state (via `-force`), then resources +may become "dangling". These are resources that physically exist but that +Terraform can no longer manage. This is sometimes preferred: you want +Terraform to stop managing resources so they can be managed some other way. +Most of the time, however, this is not intended and so Terraform protects you +from getting into this situation. + +The command-line flags are all optional. The only supported flag is: + +* `-force` - Delete the workspace even if its state is not empty. Defaults to false. + +## Example + +``` +$ terraform workspace delete example +Deleted workspace "example". +``` diff --git a/website/source/docs/commands/workspace/index.html.md b/website/source/docs/commands/workspace/index.html.md new file mode 100644 index 000000000..6b9657c40 --- /dev/null +++ b/website/source/docs/commands/workspace/index.html.md @@ -0,0 +1,21 @@ +--- +layout: "commands-workspace" +page_title: "Command: workspace" +sidebar_current: "docs-workspace-index" +description: |- + The terraform workspace command is used to manage workspaces. +--- + +# Command: workspace + +The `terraform workspace` command is used to manage +[workspaces](/docs/state/workspaces.html). + +This command is a container for further subcommands. These subcommands are +listed in the navigation bar. + +## Usage + +Usage: `terraform workspace [options] [args]` + +Please choose a subcommand from the navigation for more information. diff --git a/website/source/docs/commands/workspace/list.html.md b/website/source/docs/commands/workspace/list.html.md new file mode 100644 index 000000000..03107483e --- /dev/null +++ b/website/source/docs/commands/workspace/list.html.md @@ -0,0 +1,27 @@ +--- +layout: "commands-workspace" +page_title: "Command: workspace list" +sidebar_current: "docs-workspace-sub-list" +description: |- + The terraform workspace list command is used to list all existing workspaces. +--- + +# Command: workspace list + +The `terraform workspace list` command is used to list all existing workspaces. + +## Usage + +Usage: `terraform workspace list` + +The command will list all existing workspaces. The current workspace is +indicated using an asterisk (`*`) marker. + +## Example + +``` +$ terraform workspace list + default +* development + jsmith-test +``` diff --git a/website/source/docs/commands/workspace/new.html.md b/website/source/docs/commands/workspace/new.html.md new file mode 100644 index 000000000..e642ae042 --- /dev/null +++ b/website/source/docs/commands/workspace/new.html.md @@ -0,0 +1,49 @@ +--- +layout: "commands-workspace" +page_title: "Command: workspace new" +sidebar_current: "docs-workspace-sub-new" +description: |- + The terraform workspace new command is used to create a new workspace. +--- + +# Command: workspace new + +The `terraform workspace new` command is used to create a new workspace. + +## Usage + +Usage: `terraform workspace new [NAME]` + +This command will create a new workspace with the given name. A workspace with +this name must not already exist. + +If the `-state` flag is given, the state specified by the given path +will be copied to initialize the state for this new workspace. + +The command-line flags are all optional. The only supported flag is: + +* `-state=path` - Path to a state file to initialize the state of this environment. + +## Example: Create + +``` +$ terraform workspace new example +Created and switched to workspace "example"! + +You're now on a new, empty workspace. Workspaces isolate their state, +so if you run "terraform plan" Terraform will not see any existing state +for this configuration. +``` + +## Example: Create from State + +To create a new workspace from a pre-existing local state file: + +``` +$ terraform workspace new -state=old.terraform.tfstate example +Created and switched to workspace "example". + +You're now on a new, empty workspace. Workspaces isolate their state, +so if you run "terraform plan" Terraform will not see any existing state +for this configuration. +``` diff --git a/website/source/docs/commands/workspace/select.html.md b/website/source/docs/commands/workspace/select.html.md new file mode 100644 index 000000000..a4232face --- /dev/null +++ b/website/source/docs/commands/workspace/select.html.md @@ -0,0 +1,31 @@ +--- +layout: "commands-workspace" +page_title: "Command: workspace select" +sidebar_current: "docs-workspace-sub-select" +description: |- + The terraform workspace select command is used to choose a workspace. +--- + +# Command: env select + +The `terraform workspace select` command is used to choose a different +workspace to use for further operations. + +## Usage + +Usage: `terraform workspace select [NAME]` + +This command will select another workspace. The named workspace must already +exist. + +## Example + +``` +$ terraform workspace list + default +* development + jsmith-test + +$ terraform workspace select default +Switched to workspace "default". +``` diff --git a/website/source/layouts/commands-env.erb b/website/source/layouts/commands-env.erb deleted file mode 100644 index fdebf2c37..000000000 --- a/website/source/layouts/commands-env.erb +++ /dev/null @@ -1,38 +0,0 @@ -<% wrap_layout :inner do %> - <% content_for :sidebar do %> - - <% end %> - - <%= yield %> -<% end %> diff --git a/website/source/layouts/commands-workspace.erb b/website/source/layouts/commands-workspace.erb new file mode 100644 index 000000000..ef8d015d8 --- /dev/null +++ b/website/source/layouts/commands-workspace.erb @@ -0,0 +1,38 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %> diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a977c6a17..89a893545 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -74,7 +74,7 @@ > - env + env > @@ -140,6 +140,10 @@ > untaint + + > + workspace +