From 751038cd6df8967ce01edf9ec487fe28bece7c65 Mon Sep 17 00:00:00 2001 From: Megan Marsh Date: Mon, 1 Mar 2021 02:45:58 -0800 Subject: [PATCH] clarify onlyexcept docs further (#10679) --- website/content/docs/commands/validate.mdx | 16 ++++++++++++---- .../docs/templates/hcl_templates/onlyexcept.mdx | 9 +++++---- .../legacy_json_templates/post-processors.mdx | 9 +++++---- website/content/partials/commands/except.mdx | 13 ++++++++----- website/content/partials/commands/only.mdx | 9 ++++++--- 5 files changed, 36 insertions(+), 20 deletions(-) diff --git a/website/content/docs/commands/validate.mdx b/website/content/docs/commands/validate.mdx index 90680f1c3..e10a1de64 100644 --- a/website/content/docs/commands/validate.mdx +++ b/website/content/docs/commands/validate.mdx @@ -33,12 +33,20 @@ Errors validating build 'vmware'. 1 error(s) occurred: configuration is not validated. - `-except=foo,bar,baz` - Validates all the builds except those with the - comma-separated names. Build names by default are the names of their - builders, unless a specific `name` attribute is specified within the configuration. + comma-separated names. In legacy JSON templates, build names default to the + types of their builders (e.g. `docker` or + `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is + specified within the configuration. In HCL2 templates, the "name" is the + source block's "name" label, unless an in-build source definition adds the + "name" configuration option. - `-only=foo,bar,baz` - Only validate the builds with the given comma-separated - names. Build names by default are the names of their builders, unless a - specific `name` attribute is specified within the configuration. + names. In legacy JSON templates, build names default to the + types of their builders (e.g. `docker` or + `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is + specified within the configuration. In HCL2 templates, the "name" is the + source block's "name" label, unless an in-build source definition adds the + "name" configuration option. - `-machine-readable` Sets all output to become machine-readable on stdout. Logging, if enabled, continues to appear on stderr. diff --git a/website/content/docs/templates/hcl_templates/onlyexcept.mdx b/website/content/docs/templates/hcl_templates/onlyexcept.mdx index 3f38f9ec5..814b13ba5 100644 --- a/website/content/docs/templates/hcl_templates/onlyexcept.mdx +++ b/website/content/docs/templates/hcl_templates/onlyexcept.mdx @@ -25,9 +25,10 @@ build { sources [ "source.amazon-ebs.first-example", ] - source "source.amazon-ebs.second-example" { - // setting the name field allows to rename the source only for this build - // section. + source "source.amazon-ebs.second-example" + // setting the name field allows you to rename the source only for this + // build section. To match this builder, you need to use + // second-example-local-name, not second-example name = "second-example-local-name" } @@ -68,4 +69,4 @@ configuration: -> Note: In the cli `only` and `except` will match agains **build names** (for example:`my_build.amazon-ebs.first-example`) but in a provisioner they will -match on the **source type** (for example:`source.amazon-ebs.third-example`). +match on the **source name** (for example:`amazon-ebs.third-example`). diff --git a/website/content/docs/templates/legacy_json_templates/post-processors.mdx b/website/content/docs/templates/legacy_json_templates/post-processors.mdx index 7b958d979..167ba4168 100644 --- a/website/content/docs/templates/legacy_json_templates/post-processors.mdx +++ b/website/content/docs/templates/legacy_json_templates/post-processors.mdx @@ -169,7 +169,8 @@ option _ignores_ post-processors. ]) ``` -The values within `only` or `except` are _build names_, not builder types. If -you recall, build names by default are just their builder type, but if you -specify a custom `name` parameter, then you should use that as the value -instead of the type. +The values within `only` or `except` are _build names_, not builder types. +Name is a required block label in HCL, but in legacy JSON, build names default +to the types of their builders (e.g. `docker` or `amazon-ebs` or +`virtualbox-iso`, unless a specific `name` attribute is specified within the +configuration. diff --git a/website/content/partials/commands/except.mdx b/website/content/partials/commands/except.mdx index c7fb856b4..b0e444f8a 100644 --- a/website/content/partials/commands/except.mdx +++ b/website/content/partials/commands/except.mdx @@ -1,7 +1,10 @@ - `-except=foo,bar,baz` - Run all the builds and post-processors except those - with the given comma-separated names. Build and post-processor names by - default are their type, unless a specific `name` attribute is specified - within the configuration. Any post-processor following a skipped - post-processor will not run. Because post-processors can be nested in - arrays a different post-processor chain can still run. A post-processor + with the given comma-separated names. In legacy JSON templates, build names default to the + types of their builders (e.g. `docker` or + `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is + specified within the configuration. In HCL2 templates, the "name" is the + source block's "name" label, unless an in-build source definition adds the + "name" configuration option.Any post-processor following + a skipped post-processor will not run. Because post-processors can be nested + in arrays a different post-processor chain can still run. A post-processor with an empty name will be ignored. diff --git a/website/content/partials/commands/only.mdx b/website/content/partials/commands/only.mdx index 7486720d4..ab532b5f5 100644 --- a/website/content/partials/commands/only.mdx +++ b/website/content/partials/commands/only.mdx @@ -1,4 +1,7 @@ - `-only=foo,bar,baz` - Only run the builds with the given comma-separated - names. Build names by default are their type, unless a specific `name` - attribute is specified within the configuration. `-only` does not apply to - post-processors. + names. In legacy JSON templates, build names default to the + types of their builders (e.g. `docker` or + `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is + specified within the configuration. In HCL2 templates, the "name" is the + source block's "name" label, unless an in-build source definition adds the + "name" configuration option. \ No newline at end of file