(BOLT-1379) (docs) 'file upload' can handle directories

The 'file upload' command and the 'upload_file' function are able to
upload directories as well as individual files - these changes
explicitly mention that in the docs.

Author: caseywilliams

bolt-modules/boltlib/lib/puppet/functions/upload_file.rb

@@ -7,9 +7,9 @@
 #
 # **NOTE:** Not available in apply block
 Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunction) do
-  # Upload a file.
-  # @param source A source path, either an absolute path or a modulename/filename selector for a file in
-  #               <moduleroot>/files.
+  # Upload a file or directory.
+  # @param source A source path, either an absolute path or a modulename/filename selector for a
+  #               file or directory in <moduleroot>/files.
   # @param destination An absolute path on the target(s).
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
   # @param options Additional options: '_catch_errors', '_run_as'.
@@ -27,9 +27,9 @@
     return_type 'ResultSet'
   end
 
-  # Upload a file, logging the provided description.
-  # @param source A source path, either an absolute path or a modulename/filename selector for a file in
-  #               <moduleroot>/files.
+  # Upload a file or directory, logging the provided description.
+  # @param source A source path, either an absolute path or a modulename/filename selector for a
+  #               file or directory in <moduleroot>/files.
   # @param destination An absolute path on the target(s).
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
   # @param description A description to be output when calling this function.

lib/bolt/bolt_option_parser.rb

@@ -22,7 +22,7 @@ def self.examples(cmd, desc)
 
 Available subcommands:
   bolt command run <command>       Run a command remotely
-  bolt file upload <src> <dest>    Upload a local file
+  bolt file upload <src> <dest>    Upload a local file or directory
   bolt script run <script>         Upload a local script and run it remotely
   bolt task show                   Show list of available tasks
   bolt task show <task>            Show documentation for task
@@ -93,7 +93,7 @@ def self.examples(cmd, desc)
 Usage: bolt file <action> [options]
 
 Available actions are:
-  upload <src> <dest>              Upload local file <src> to <dest> on each node
+  upload <src> <dest>              Upload local file or directory <src> to <dest> on each node
 
 #{examples('file upload /tmp/source /etc/profile.d/login.sh', 'upload a file to')}
 Available options are:

pre-docs/bolt_command_reference.md

@@ -13,7 +13,7 @@ Bolt commands use the syntax: `bolt <subcommand> <action> [options]`
 | `bolt task run` | Runs a task on a remote system, passing any specified parameters. | - The task name, in the format `modulename::taskname`.<br>- The nodes on which to run the task.
 | `bolt plan run` | Runs a task plan. | - The plan name, in the format `modulename::planname`.<br>- The nodes on which to run the plan.
 | `bolt apply` | Applies a Puppet manifest file. | - The path to the manifest file.<br>- The nodes on which to run the plan.
-| `bolt file upload` | Uploads a local file to a remote node. | - The path to the source file.<br>- The path to the remote location.<br>- The nodes on which to upload the file.
+| `bolt file upload` | Uploads a local file or directory to a remote node. | - The path to the source file or directory.<br>- The path to the remote location.<br>- The nodes on which to upload the file or directory.
 | `bolt task show` | Lists all the tasks on the modulepath that have not been marked `private`. Will note whether a task supports no-operation mode. | - Adding a specific task name displays details and parameters for the task.<br>- Optionally, the name of a task you want details for: `bolt task show <TASK NAME>`
 | `bolt plan show` | Lists the plans that are installed on the current module path. | - Adding a specific plan name displays details and parameters for the plan.
 | `bolt plan convert` | Converts a YAML plan to a Puppet plan | - The path (relative or absolute) to the YAML plan to be converted.

pre-docs/plan_functions.md

@@ -645,16 +645,16 @@ This function does nothing if the list of targets is empty.
 **NOTE:** Not available in apply block
 
 
-### Upload a file.
+### Upload a file or directory.
 
 ```
 upload_file(String[1] $source, String[1] $destination, Boltlib::TargetSpec $targets, Optional[Hash[String[1], Any]] $options)
 ```
 
 *Returns:* `ResultSet` A list of results, one entry per target.
 
-* **source** `String[1]` A source path, either an absolute path or a modulename/filename selector for a file in
-<moduleroot>/files.
+* **source** `String[1]` A source path, either an absolute path or a modulename/filename selector for a
+file or directory in <moduleroot>/files.
 * **destination** `String[1]` An absolute path on the target(s).
 * **targets** `Boltlib::TargetSpec` A pattern identifying zero or more targets. See [`get_targets`](#get_targets) for accepted patterns.
 * **options** `Optional[Hash[String[1], Any]]` Additional options: '_catch_errors', '_run_as'.
@@ -668,16 +668,16 @@ upload_file('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, '_run_as' => '
 upload_file('postgres/default.conf', 'C:/ProgramData/postgres/default.conf', $target)
 ```
 
-### Upload a file, logging the provided description.
+### Upload a file or directory, logging the provided description.
 
 ```
 upload_file(String[1] $source, String[1] $destination, Boltlib::TargetSpec $targets, String $description, Optional[Hash[String[1], Any]] $options)
 ```
 
 *Returns:* `ResultSet` A list of results, one entry per target.
 
-* **source** `String[1]` A source path, either an absolute path or a modulename/filename selector for a file in
-<moduleroot>/files.
+* **source** `String[1]` A source path, either an absolute path or a modulename/filename selector for a
+file or directory in <moduleroot>/files.
 * **destination** `String[1]` An absolute path on the target(s).
 * **targets** `Boltlib::TargetSpec` A pattern identifying zero or more targets. See [`get_targets`](#get_targets) for accepted patterns.
 * **description** `String` A description to be output when calling this function.

pre-docs/running_bolt_commands.md

@@ -98,13 +98,13 @@ winrm:
    extensions: [.py, .pl]
 ```
 
-## Upload files to remote nodes
+## Upload files or directories to remote nodes
 
-Use Bolt to copy files to remote nodes.
+Use Bolt to copy files or directories to remote nodes.
 
 **Note:** Most transports are not optimized for file copying, so this command is best limited to small files.
 
--   To upload a file to a remote node, run the `bolt file upload` command. Specify the local path to the file, the destination location, and the target nodes.
+-   To upload a file or directory to a remote node, run the `bolt file upload` command. Specify the local path to the file or directory, the destination location, and the target nodes.
 
 ```
 bolt file upload <SOURCE> <DESTINATION> --nodes <NODE NAME>,<NODE NAME>