Merge pull request #5291 from chef/lcg/document-voodoo

Document strange config_context :knife voodoo 

2 files changed, 20 insertions, 0 deletions

diff --git a/chef-config/lib/chef-config/config.rb b/chef-config/lib/chef-config/config.rb
index f46419937a..be5ca2099c 100644
--- a/chef-config/lib/chef-config/config.rb
+++ b/chef-config/lib/chef-config/config.rb
@@ -661,6 +661,20 @@ module ChefConfig
 
     # knife configuration data
     config_context :knife do
+      # XXX: none of these default values are applied to knife (and would create a backcompat
+      # break in knife if this bug was fixed since many of the defaults below are wrong).  this appears
+      # to be the start of an attempt to be able to use config_strict_mode true?  if so, this approach
+      # is fraught with peril because this namespace is used by every knife plugin in the wild and
+      # we would need to validate every cli option in every knife attribute out there and list them all here.
+      #
+      # based on the way that people may define `knife[:foobar] = "something"` for the knife-foobar
+      # gem plugin i'm pretty certain we can never turn on anything like config_string_mode since
+      # any config value may be a typo or it may be in some gem in some knife plugin we don't know about.
+      #
+      # we do still need to maintain at least one of these so that the knife config hash gets
+      # created.
+      #
+      # this whole situation is deeply unsatisfying.
       default :ssh_port, nil
       default :ssh_user, nil
       default :ssh_attribute, nil
diff --git a/lib/chef/knife.rb b/lib/chef/knife.rb
index 2d64798bda..c9ecfbf0cc 100644
--- a/lib/chef/knife.rb
+++ b/lib/chef/knife.rb
@@ -336,6 +336,12 @@ class Chef
 
     # extracts the settings from the Chef::Config[:knife] sub-hash that correspond
     # to knife cli options -- in preparation for merging config values with cli values
+    #
+    # NOTE: due to weirdness in mixlib-config #has_key? is only true if the value has
+    # been set by the user -- the Chef::Config defaults return #has_key?() of false and
+    # this code DEPENDS on that functionality since applying the default values in
+    # Chef::Config[:knife] would break the defaults in the cli that we would otherwise
+    # overwrite.
     def config_file_settings
       cli_keys.each_with_object({}) do |key, memo|
         memo[key] = Chef::Config[:knife][key] if Chef::Config[:knife].has_key?(key)