document clearly what keep_input_artifact does for each post-processor

packer/build.go

@@ -281,7 +281,7 @@ PostProcessorRunSeqLoop:
 			// useless if keep isn't set, force an override that still uses
 			// post-processor preference instead of user preference.
 			if corePP.keepInputArtifact != nil {
-				if *corePP.keepInputArtifact == false && forceOverride {
+				if defaultKeep && *corePP.keepInputArtifact == false && forceOverride {
 					log.Printf("The %s post-processor forces "+
 						"keep_input_artifact=true to preserve integrity of the"+
 						"build chain. User-set keep_input_artifact=false will be"+

website/source/docs/post-processors/alicloud-import.html.md

@@ -60,6 +60,9 @@ are two categories: required and optional parameters.
 
 ### Optional:
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the RAW or VHD
+    disk image after importing it to the cloud. Defaults to false.
+
 -   `oss_key_name` (string) - The name of the object key in `oss_bucket_name`
     where the RAW or VHD file will be copied to for import.
 

website/source/docs/post-processors/amazon-import.html.md

@@ -101,6 +101,9 @@ Optional:
 -   `insecure_skip_tls_verify` (boolean) - This allows skipping TLS
     verification of the AWS EC2 endpoint. The default is `false`.
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the source virtual
+    machine image after importing it to the cloud. Defaults to false.
+
 -   `license_type` (string) - The license type to be used for the Amazon
     Machine Image (AMI) after importing. Valid values: `AWS` or `BYOL`
     (default). For more details regarding licensing, see

website/source/docs/post-processors/artifice.html.md

@@ -59,6 +59,11 @@ The configuration allows you to specify which files comprise your artifact.
     packer is complete. These will replace any of the builder's original
     artifacts (such as a VM snapshot).
 
+### Optional:
+
+-   `keep_input_artifact` (boolean) - if true, do not delete the original
+    artifact files after creating your new artifact. Defaults to true.
+
 ### Example Configuration
 
 This minimal example:

website/source/docs/post-processors/checksum.html.md

@@ -43,6 +43,11 @@ Optional parameters:
 
 -   `checksum_types` (array of strings) - An array of strings of checksum types
     to compute. Allowed values are md5, sha1, sha224, sha256, sha384, sha512.
+
+-   `keep_input_artifact` (boolean) - Unlike most post-processors, setting
+    `keep_input_artifact` will have no effect; the checksum post-processor
+    always saves the artifact that it is calculating the checksum for.
+
 -   `output` (string) - Specify filename to store checksums. This defaults to
     `packer_{{.BuildName}}_{{.BuilderType}}_{{.ChecksumType}}.checksum`. For
     example, if you had a builder named `database`, you might see the file

website/source/docs/post-processors/compress.html.md

@@ -38,7 +38,9 @@ you will need to specify the `output` option.
     algorithms that support it, from 1 through 9 inclusive. Typically higher
     compression levels take longer but produce smaller files. Defaults to `6`
 
--   `keep_input_artifact` (boolean) - Keep source files; defaults to `false`
+-   `keep_input_artifact` (boolean) - if `true`, keep both the source files and
+    the compressed file; if `false`, discard the source files. Defaults to
+    `false`
 
 ### Supported Formats
 

website/source/docs/post-processors/digitalocean-import.html.md

@@ -67,6 +67,9 @@ Optional:
 -   `image_tags` (array of strings) - A list of tags to apply to the resulting
     imported image.
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the source virtual
+    machine image after importing it to the cloud. Defaults to false.
+
 -   `skip_clean` (boolean) - Whether we should skip removing the image file
     uploaded to Spaces after the import process has completed. "true" means
     that we should leave it in the Space, "false" means to clean it out.

website/source/docs/post-processors/docker-import.html.md

@@ -38,6 +38,9 @@ is optional.
     commit. Example of instructions are `CMD`, `ENTRYPOINT`, `ENV`, and
     `EXPOSE`. Example: `[ "USER ubuntu", "WORKDIR /app", "EXPOSE 8080" ]`
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the source tar
+    after importing it to docker. Defaults to false.
+
 ## Example
 
 An example is shown below, showing only the post-processor configuration:

website/source/docs/post-processors/docker-push.html.md

@@ -42,6 +42,10 @@ This post-processor has only optional configuration:
     the duration of the push. If true `login_server` is required and `login`,
     `login_username`, and `login_password` will be ignored.
 
+-   `keep_input_artifact` (boolean) - if true, do not delete the docker image
+    after pushing it to the cloud. Defaults to true, but can be set to false if
+    you do not need to save your local copy of the docker container.
+
 -   `login` (boolean) - Defaults to false. If true, the post-processor will
     login prior to pushing. For log into ECR see `ecr_login`.
 

website/source/docs/post-processors/docker-save.html.md

@@ -24,10 +24,17 @@ familiar with this and vice versa.
 
 ## Configuration
 
+### Required
+
 The configuration for this post-processor only requires one option.
 
 -   `path` (string) - The path to save the image.
 
+### Optional
+
+-   `keep_input_artifact` (boolean) - if true, do not delete the docker
+	container, and only save the .tar created by docker save. Defaults to true.
+
 ## Example
 
 An example is shown below, showing only the post-processor configuration:

website/source/docs/post-processors/docker-tag.html.md

@@ -38,6 +38,13 @@ settings are optional.
     after 1.12.0.
     [reference](https://docs.docker.com/engine/deprecated/#/f-flag-on-docker-tag)
 
+-   `keep_input_artifact` (boolean) - Unlike most other post-processors, the
+    keep_input_artifact option will have no effect for the docker-tag
+    post-processor. We will always retain the input artifact for docker-tag,
+    since deleting the image we just tagged is not a behavior anyone should ever
+    expect. `keep_input_artifact will` therefore always be evaluated as true,
+    regardless of the value you enter into this field.
+
 ## Example
 
 An example is shown below, showing only the post-processor configuration:

website/source/docs/post-processors/googlecompute-export.html.md

@@ -45,8 +45,8 @@ permissions to the GCS `paths`.
 -   `disk_type` (string) - Type of disk used to back export instance, like
     `pd-ssd` or `pd-standard`. Defaults to `pd-ssd`.
 
--   `keep_input_artifact` (boolean) - If true, do not delete the Google Compute
-    Engine (GCE) image being exported.
+-   `keep_input_artifact` (boolean) - If `true`, do not delete the Google Compute
+    Engine (GCE) image being exported. defaults to `false`.
 
 -   `machine_type` (string) - The export instance machine type. Defaults
     to `"n1-highcpu-4"`.

website/source/docs/post-processors/manifest.html.md

@@ -40,6 +40,13 @@ post-processors such as Docker and Artifice.
     file. This defaults to false.
 -   `custom_data` (map of strings) Arbitrary data to add to the manifest.
 
+-   `keep_input_artifact` (boolean) - Unlike most other post-processors, the
+    keep_input_artifact option will have no effect for the manifest
+    post-processor. We will always retain the input artifact for manifest,
+    since deleting the files we just recorded is not a behavior anyone should
+    ever expect. `keep_input_artifact will` therefore always be evaluated as
+    true, regardless of the value you enter into this field.
+
 ### Example Configuration
 
 You can simply add `{"type":"manifest"}` to your post-processor section. Below

website/source/docs/post-processors/shell-local.html.md

@@ -101,6 +101,15 @@ Optional parameters:
     like the `-e` flag, otherwise individual steps failing won't fail the
     provisioner.
 
+-   `keep_input_artifact` (boolean) - Unlike most other post-processors, the
+    keep_input_artifact option will have no effect for the shell-local
+    post-processor. Packer will always retain the input artifact for
+    shell-local, since the shell-local post-processor merely passes forward the
+    artifact it receives. If your shell-local post-processor produces a file or
+    files which you would like to have replace the input artifact, you may
+    overwrite the input artifact using the [artifice](./artifice.html)
+    post-processor after your shell-local processor has run.
+
 -   `only_on` (array of strings) - This is an array of [runtime operating
     systems](https://golang.org/doc/install/source#environment) where
     `shell-local` will execute. This allows you to execute `shell-local` *only*

website/source/docs/post-processors/vagrant-cloud.html.md

@@ -84,6 +84,9 @@ on Vagrant Cloud, as well as authentication and version information.
     to set this option to true if your host at vagrant_cloud_url is using a
     self-signed certificate.
 
+-   `keep_input_artifact` (boolean) - When true, preserve the local box
+    after uploading to Vagrant cloud. Defaults to `true`.
+
 -   `version_description` (string) - Optionally markdown text used as a
     full-length and in-depth description of the version, typically for denoting
     changes introduced

website/source/docs/post-processors/vagrant.html.md

@@ -65,8 +65,12 @@ more details about certain options in following sections.
     Vagrant box (regardless of their paths). They can then be used from the
     Vagrantfile.
 
--   `keep_input_artifact` (boolean) - If set to true, do not delete the
-    `output_directory` on a successful build. Defaults to false.
+-   `keep_input_artifact` (boolean) - When true, preserve the artifact we use to
+    create the vagrant box. Defaults to `false`, except when you set a cloud
+    provider (e.g. aws, azure, google, digitalocean). In these cases deleting
+    the input artifact would render the vagrant box useless, so we always keep
+    these artifacts -- even if you specifically set
+    `"keep_input_artifact":false`
 
 -   `output` (string) - The full path to the box file that will be created by
     this post-processor. This is a [configuration

website/source/docs/post-processors/vsphere-template.html.md

@@ -61,6 +61,12 @@ Optional:
 -   `insecure` (boolean) - If it's true skip verification of server
     certificate. Default is false
 
+-   `keep_input_artifact` (boolean) - Unlike most post-processors, this option
+    has no effect for vsphere-template. This is because in order for a template
+    to work, you can't delete the vm that you generate the template from. The
+    vsphere template post-processor will therefore always preserve the original
+    vm.
+
 -   `snapshot_enable` (boolean) - Create a snapshot before marking as a
     template. Default is false
 

website/source/docs/post-processors/vsphere.html.md

@@ -54,6 +54,9 @@ Optional:
 -   `insecure` (boolean) - Whether or not the connection to vSphere can be done
     over an insecure connection. By default this is false.
 
+-   `keep_input_artifact` (boolean) - When `true`, preserve the local VM files,
+    even after importing them to vsphere. Defaults to `false`.
+
 -   `resource_pool` (string) - The resource pool to upload the VM to.
 
 -   `vm_folder` (string) - The folder within the datastore to store the VM.