Merge pull request #26 from nfagerlund/ticket/2.6.x/8302_exec_provider_docs

Ticket/2.6.x/8302 exec provider docs

2 files changed, 17 insertions, 5 deletions

diff --git a/lib/puppet/provider/exec/posix.rb b/lib/puppet/provider/exec/posix.rb
index 92dbd8c98..157d0f28d 100644
--- a/lib/puppet/provider/exec/posix.rb
+++ b/lib/puppet/provider/exec/posix.rb
@@ -4,9 +4,12 @@ Puppet::Type.type(:exec).provide :posix do
   confine :feature => :posix
   defaultfor :feature => :posix
 
-  desc "Execute external binaries directly, on POSIX systems.
-This does not pass through a shell, or perform any interpolation, but
-only directly calls the command with the arguments given."
+  desc <<-EOT
+    Executes external binaries directly, without passing through a shell or
+    performing any interpolation. This is a safer and more predictable way
+    to execute most commands, but prevents the use of globbing and shell
+    built-ins (including control logic like "for" and "if" statements).
+  EOT
 
   def run(command, check = false)
     output = nil
diff --git a/lib/puppet/provider/exec/shell.rb b/lib/puppet/provider/exec/shell.rb
index 98f309e8f..ad2171005 100644
--- a/lib/puppet/provider/exec/shell.rb
+++ b/lib/puppet/provider/exec/shell.rb
@@ -3,8 +3,17 @@ Puppet::Type.type(:exec).provide :shell, :parent => :posix do
 
   confine :feature => :posix
 
-  desc "Execute external binaries directly, on POSIX systems.
-passing through a shell so that shell built ins are available."
+  desc <<-EOT
+    Passes the provided command through `/bin/sh`; only available on
+    POSIX systems. This allows the use of shell globbing and built-ins, and
+    does not require that the path to a command be fully-qualified. Although
+    this can be more convenient than the `posix` provider, it also means that
+    you need to be more careful with escaping; as ever, with great power comes
+    etc. etc.
+
+    This provider closely resembles the behavior of the `exec` type
+    in Puppet 0.25.x.
+  EOT
 
   def run(command, check = false)
     command = %Q{/bin/sh -c "#{command.gsub(/"/,'\"')}"}