octocatalog-diff 1.5.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 154a03508f5cbae0bafaedf90773e5dc82624a4e
-  data.tar.gz: 3dca1d51a606a0f31ee935eef370a7347a72af39
+SHA256:
+  metadata.gz: 07e53efa197ece3d868ab453f200b49d6fc0718fcd40e8201ab92d04e4787871
+  data.tar.gz: e60db7eb374631ec5a4f430b58b16f57772e081aeea3b12d7576e3265df4ae6b
 SHA512:
-  metadata.gz: 961a4c0cf1677d9262010e17e88f7ca8387d548886c83ac7f34a86540d09fc864519d906a3172edaef8140f9505539a65437259f13d72257dfe1bd3f161561e2
-  data.tar.gz: 2f822d309b8ebbd39f923c15b6849b02dd836b3bf8cb6d5354cea0fe873828196fac73af1ed801c6f96460339ca9032a27341e1eda2d090d8fa7f2f71a373654
+  metadata.gz: 2b6ce06f9d1d91f8bfeb12f731a8b8d901b794396dd34a6b3e2d29b8e4e7e59d02ceb1f1bdce89ac73d6d3ad14beb2883188810c778ed6ccb431a30b05a9d7b3
+  data.tar.gz: 2f712011fd71e32caf2bf3e453ce16cae41c2be79a6bdfa12ed0d3bdc1ce62751e86c6f4eea500d243f8a69adf6642f1009250c88b5b85cb1af2ddee67e3a7a0

data/.version

@@ -1 +1 @@
-1.5.2
+2.1.0

data/README.md

@@ -1,4 +1,4 @@
-# octocatalog-diff
+# octocatalog-diff ![CI](https://github.com/github/octocatalog-diff/workflows/CI/badge.svg)
 
 #### Compile Puppet catalogs from 2 branches, versions, etc., and compare them <img src="/doc/images/octocatolog-diff-logo.png" align="right" height=126 width=240>
 
@@ -23,7 +23,7 @@ There are some [limitations](doc/limitations.md) to a catalog-based approach, me
 `octocatalog-diff` is currently able to get catalogs by the following methods:
 - Compile catalog via the command line with a Puppet agent on your machine (as GitHub uses the tool internally)
 - Obtain catalog over the network from PuppetDB
-- Obtain catalog over the network using the API to query a Puppet Master / PuppetServer (Puppet 3.x and 4.x supported)
+- Obtain catalog over the network using the API to query a Puppet Master / PuppetServer (Puppet 3.x through 6.x supported)
 - Read catalog from a JSON file
 
 ## Example
@@ -81,6 +81,6 @@ If you have a problem or suggestion, please [open an issue](https://github.com/g
 
 It requires 3rd party ruby gems found [here](/vendor/cache). It also includes portions of other open source projects [here](/lib/octocatalog-diff/external/pson), [here](/spec/octocatalog-diff/fixtures/repos/default/modules/stdlib), [here](/spec/octocatalog-diff/support/httparty) and [here](/spec/octocatalog-diff/tests/external/pson). All 3rd party code and required gems are licensed either as MIT or Apache 2.0.
 
-## Authors
+## Authors / Owners
 
-`octocatalog-diff` was designed and authored by [Kevin Paulisse](https://github.com/kpaulisse) and is now maintained, reviewed, and tested by Kevin and the rest of the Site Reliability Engineering team at GitHub.
+`octocatalog-diff` was originally designed and authored by [Kevin Paulisse](https://github.com/kpaulisse). It is now maintained by the Site Reliability Engineering team at GitHub.

data/doc/CHANGELOG.md

@@ -8,6 +8,56 @@
 </tr>
 </thead><tbody>
 
+<tr valign=top>
+<td>2.1.0</td>
+<td>2020-02-18</td>
+
+<li><a href="https://github.com/github/octocatalog-diff/pull/240">#240</a>: (Enhancement) Run CI against Puppet 7 and Ruby 3</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/241">#241</a>: (Bug Fix) Fix indent and numbering in several docs</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/242">#242</a>: (Enhancement) Handle JSON facts structured as name/values</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/244">#244</a>: (Enhancement) Update capability and docs of --compare-file-text</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>2.0.0</td>
+<td>2020-01-12</td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/226">#226</a>: (Enhancement) Add Puppet 6 support</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/228">#228</a>: (Enhancement) Add Puppetserver catalog v4 API support</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/229">#229</a>: (Enhancement) Add support for PE package inventory facts</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/230">#230</a>: (Enhancement) Add set quality comparison to ignore filter</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>1.6.0</td>
+<td>2019-10-31</td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/216">#216</a>: (Enhancement) Hide sensitive parameters</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/204">#204</a>: (Enhancement) Add glob support for modulepath</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/206">#206</a>: (Bug Fix) Fix multi-node list with parallel mode</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/215">#215</a>: (Bug Fix) Add Support for Hashdiff 1.0.0</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>1.5.4</td>
+<td>2018-12-11</td>
+<td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/190">#190</a>: (Enhancement) Additional filtered out cases for compilation directory</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/195">#195</a>: (Enhancement) Parallel catalog-diff when multiple hostnames are passed</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/198">#198</a>: (Bug Fix) Portability fixes</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/200">#200</a>: (Bug Fix) Support name parameter when validating references</li>
+</td>
+</tr>
+
+<tr valign=top>
+<td>1.5.3</td>
+<td>2018-03-05</td>
+<td>
+<li><a href="https://github.com/github/octocatalog-diff/pull/176">#176</a>: (Enhancement) Normalize file resource titles in reference checks</li>
+</td>
+</tr>
+
 <tr valign=top>
 <td>1.5.2</td>
 <td>2017-12-19</td>

data/doc/advanced-compare-file-text.md

@@ -0,0 +1,79 @@
+# Compare file text
+
+`octocatalog-diff` contains functionality to detect changes in file content for file resources that use the `source` attribute like this:
+
+```
+file { '/etc/logrotate.d/my-service.conf':
+  source => 'puppet:///modules/logrotate/etc/logrotate.d/my-service.conf',
+}
+```
+
+When the `source` attribute is used, the catalog contains the value of the attribute (in the example above, `source` = `puppet:///modules/logrotate/etc/logrotate.d/my-service.conf`). However, the catalog does not contain the content of the file. When an agent applies the catalog, the file found on the server or in the code base at `modules/logrotate/file/etc/logrotate.d/my-service.conf` will be installed into `/etc/logrotate.d/my-service.conf`.
+
+If a developer creates a change to this file, the catalog will not indicate this change. This means that so long as the `source` location does not change, any tool analyzing just the catalog would not detect a "diff" resulting from changes in the underlying file itself.
+
+However, since applying the catalog could change the content of a file on the target node, `octocatalog-diff` has a feature that will do the following for any `source => 'puppet:///modules/...'` files:
+
+- Locate the source file in the Puppet code
+- Substitute the content of the file into the generated catalog (remove `source` and populate `content`)
+- Display the "diff" in the now-populated `content` field
+
+This feature is available only when the catalogs are being compiled from local code. This feature is not available, and will be automatically disabled, when pulling catalogs from PuppetDB or a Puppet server.
+
+Note: In Puppet >= 4.4 there is an option in Puppet itself called "static catalogs" which if enabled will cause the checksum of the file to be included in the catalog. However, the `octocatalog-diff` feature described here is still useful because it can be used to display a "diff" of the change rather than just displaying a "diff" of a checksum.
+## Command line options
+
+### `--compare-file-text` and `--no-compare-file-text`
+
+The feature described above is enabled by default, and no special setup is required.
+
+To disable this feature for a specific run, add `--no-compare-file-text` to the command line.
+
+To disable this feature by default, add the following to a [configuration](/doc/configuration.md) file:
+
+```ruby
+settings[:compare_file_text] = false
+```
+
+If this feature is disabled by default in a configuration file, add `--compare-file-text` to enable the feature for this specific run.
+
+Note that the feature will be automatically disabled, regardless of configuration or command line options, if catalogs are being pulled from PuppetDB or a Puppet server.
+
+### `--compare-file-text-ignore-tags`
+
+To disable this feature for specific `file` resources, set a tag on the resources for which the comparison is undesired. For example:
+
+```
+file { '/etc/logrotate.d/my-service.conf':
+  source => 'puppet:///modules/logrotate/etc/logrotate.d/my-service.conf',
+}
+
+file { '/etc/logrotate.d/other-service.conf':
+  tag    => ['compare-file-text-disable'],
+  source => 'puppet:///modules/logrotate/etc/logrotate.d/other-service.conf',
+}
+```
+
+Inform `octocatalog-diff` of the name of the tag either via the command line (`--compare-file-text-ignore-tags "compare-file-text-disable"`) or via a [configuration](/doc/configuration.md) file:
+
+```ruby
+settings[:compare_file_text_ignore_tags] = %w(compare-file-text-disable)
+```
+
+With this example setup, the file text would be compared for `/etc/logrotate.d/my-service.conf` but would NOT be compared for `/etc/logrotate.d/other-service.conf`.
+
+Notes:
+
+1. `--compare-file-text-ignore-tags` can take comma-separated arguments if there are multiple tags, e.g.: `--compare-file-text-ignore-tags tag1,tag2`.
+
+1. When defining values in the configuration file, `settings[:compare_file_text_ignore_tags]` must be an array. (The default value is an empty array, `[]`.)
+
+1. "compare-file-text-disable" is used as the name of the tag in the example above, but it is not a magical value. Any valid tag name can be used.
+
+## Notes
+
+1. If the underlying file source cannot be found when building the "to" catalog, an exception will be raised. This will display the resource type and title, the value of `source` that is invalid, and the file name and line number of the Puppet manifest that declared the resource.
+
+1. If the underlying file source cannot be found when building the "from" catalog, no exception will be raised. This behavior allows `octocatalog-diff` to work correctly even if there is a problem in the "from" catalog that is being corrected in the "to" catalog. (Of course, if the underlying file source can't be found in the "to" catalog either, an exception is raised -- see #1.)
+
+1. No processing takes place for file `source` whose values do not start with `puppet:///modules/`.

data/doc/advanced-environments.md

@@ -15,13 +15,13 @@ If you are using environment names to control the behavior of Puppet, this defau
 When you supply the command line argument `--preserve-environments` (or set `settings[:preserve_environments] = true` in your [configuration file](/doc/configuration.md)), `octocatalog-diff` will instead do the following:
 
 1. Create a temporary directory
-2. Create the following symlinks from `<temporary directory>` to the corresponding directories in the checkout of your code:
+1. Create the following symlinks from `<temporary directory>` to the corresponding directories in the checkout of your code:
 
-  - `environments`
-  - `manifests`
-  - `modules`
+    - `environments`
+    - `manifests`
+    - `modules`
 
-3. Run Puppet using an environment you specify via the command line
+1. Run Puppet using an environment you specify via the command line
 
 Note that you must have set `--preserve-environments` in order for the `--environment` and/or `--create-symlinks` options (described below) to have any effect.
 

data/doc/advanced-ignores.md

@@ -222,3 +222,13 @@ File[/tmp/foo] =>
 In this case, the very important line was removed from the catalog, and you want to know about this. Ignoring `File[/tmp/foo]::parameters::content` would have suppressed this (because all changes to that attribute are ignored). Also ignoring `File[/tmp/foo]::parameters::content=~>This is the line in the new catalog that I do not care about$` would have also suppressed this (because the regular expression was matched for *one* of the lines). However, the two examples with `=&>` in this section would *not* have suppressed this change, because it is no longer the case that *all* changes in the file matched the regular expression.
 
 :warning: All lines are stripped of leading and trailing spaces before the regular expression match is tried. This stripping of whitespace is done *only* for this comparison stage, and does not affect the display of any results.
+
+#### Ignoring attributes which have identical elements but in arbitrary order
+
+You can ignore attributes where both the values in both the old and new catalogs are arrays and the arrays
+contain identical elements but in arbitrary order. Basically, you can ignore a parameter where the values
+have set equality.
+
+To ignore any parameters named `foo` with values having set equality, you would use:
+
+      --ignore 'My::Custom::Resource[*]::parameters::foo=s>='

data/doc/advanced-puppet-master.md

@@ -4,11 +4,15 @@
 
 Please note the following caveats:
 
-0. This method will put some load on your Puppet Master to build the catalog. Depending on how you use `octocatalog-diff` you should ensure that this extra load will not overwhelm your Puppet Master (especially if you create a "thundering herd" by launching several instances of `octocatalog-diff` simultaneously).
+1. This method will put some load on your Puppet Master to build the catalog. Depending on how you use `octocatalog-diff` you should ensure that this extra load will not overwhelm your Puppet Master (especially if you create a "thundering herd" by launching several instances of `octocatalog-diff` simultaneously).
 
-0. You will need to deploy your Puppet code to an environment on your Puppet Master prior to running `octocatalog-diff` for that environment. `octocatalog-diff` does not deploy code for you.
+1. You will need to deploy your Puppet code to an environment on your Puppet Master prior to running `octocatalog-diff` for that environment. `octocatalog-diff` does not deploy code for you.
 
-0. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below.
+1. You will need to configure authorization for one or more whitelisted certificates on your Puppet Master. The default permissions allow a node to retrieve its own catalog via the API, but you need a certificate for `octocatalog-diff` that permits it to retrieve any catalog. See the [Certificate authorization](#certificate-authorization) section below. If you are using Puppet Enterprise and use
+the Puppet Master v4 API you may also use a Puppet Enterprise RBAC token. The user owning the token will need the "Puppet Server Compile catalogs for remote nodes" permission.
+See the [PE RBAC Token Authorization](#pe-rbac-token-authorization) section below.
+
+1. If you are using the v2 or v3 PuppetServer APIs with Octocatalog-Diff to compile catalogs, then those catalogs and facts will be automatically stored in PuppetDB. However, when using the v4 PuppetServer API with Octocatalog-Diff, facts and catalogs are *not* automatically stored in PuppetDB - persistence is optional and may be enabled with the appropriate Octocatalog-Diff CLI flag. If your environment depends on the accuracy of exported resources or facts in PuppetDB, you may wish to upgrade and use the V4 API, to avoid unintentional side-effects.
 
 ## Command line options
 
@@ -18,11 +22,15 @@ The following command line options are used to retrieve a catalog from a Puppet
 | ------ | ----------- |
 | `-f ENVIRONMENT` | Environment name to use for the "from" catalog |
 | `-t ENVIRONMENT` | Environment name to use for the "to" catalog |
-| `--puppet-master HOSTNAME:PORT | The hostname and port number of the Puppet Master. (By default the port used by Puppet Master is 8140.) |
-| `--puppet-master-api-version VERSION | The API version used by the Puppet Master. API versions 2 and 3 are supported. Puppet Master 3.x uses API version 2, and the PuppetServer for Puppet 4.x uses API version 3. By default, API version 3 is used, so you only need to set this option if you are using Puppet Master 3.x. |
+| `--puppet-master HOSTNAME:PORT` | The hostname and port number of the Puppet Master. (By default the port used by Puppet Master is 8140.) |
+| `--puppet-master-api-version VERSION` | The API version used by the Puppet Master. API versions 2, 3,and 4 are supported. Puppet Master 3.x uses API version 2, and the PuppetServer for Puppet 4.x uses API version 3. PuppetServer 6.3.0 introduced the optional use of the v4 API but still fully supports the v3 API. By default, API version 3 is used, so you only need to set this option if you are using Puppet Master 3.x or wish to use the newer v4 API with PuppetServer 6. |
 | `--puppet-master-ssl-ca PATH` | Path to the CA certificate (public portion of certificate only) for your Puppet Master. This file will be on your Puppet Master and all Puppet agents. You can find it by running `puppet config print cacert` on any Puppet-managed host. |
-| `--puppet-master-ssl-client-cert PATH` | Path to the client certificate. Please see the section below on certificate authentication. |
-| `--puppet-master-ssl-client-key PATH` | Path to the client private key. Please see the section below on certificate authentication. |
+| `--puppet-master-ssl-client-cert PATH` | Path to the client certificate. Please see the section below on certificate authentication. This can be omitted if using PE RBAC token based auth with the v4 API. |
+| `--puppet-master-ssl-client-key PATH` | Path to the client private key. Please see the section below on certificate authentication. This can be omitted if using PE RBAC token based auth with the v4 API. |
+| `--puppet-master-token STRING` | A PE RBAC token used to authenticate a v4 catalog compile, in lieu of using certificate authentication. Please see the section below on token authentication. |
+| `--puppet-master-token-file PATH` | A path to a file containing a PE RBAC token used to authenticate a v4 catalog compile, in lieu of using certificate authentication. If this and `--puppet-master-token` are both specified, `--puppet-master-token` will be used instead. Please see the section below on token authentication. |
+| `--puppet-master-update-catalog` | When using the v4 API, instruct the PuppetServer to update the catalog generated from the compile in its PuppetDB instance. When using v2 and v3 APIs the catalog is always updated and this option is ignored. |
+| `--puppet-master-update-facts` | When using the v4 API, instruct the PuppetServer to update the facts used during the compile in its PuppetDB instance. When using v2 and v3 APIs the facts are always updated and this option is ignored. |
 
 If you wish to use a different Puppet Master to compile the "to" and "from" catalogs, you may prefix any of the `--puppet-master...` options with `to` or `from`. For example, perhaps you are testing an upgrade from Puppet 3.x to 4.x. You could use:
 
@@ -48,3 +56,13 @@ allow $1
 ```
 
 Please follow the instructions for the version of Puppet Master, PuppetServer, or Puppet Enterprise that you are using in order to generate and authorize the certificates.
+
+## PE RBAC Token authorization
+
+In newer versions of Puppet Enterprise you can authenticate using a valid PE RBAC token with appropriate permissions as long as it is authorized in the PuppetServer `auth.conf` file.
+
+By default this permission is enabled and controlled by the `puppet_enterprise::master::tk_authz::allow_rbac_catalog_compile` Hiera setting.
+
+The user the token was issued to must have the `puppetserver:compile_catalogs:*` permission.
+
+Note: A Puppet catalog may contain unencrypted secrets, even ones marked as `Sensitive`. In order to perform its job, Octocatalog-Diff needs access to the catalog. By granting a user the above RBAC permission you are granting them the ability to retrieve and view the complete catalog resulting from a compile, including any included secrets.

data/doc/configuration-puppet.md

@@ -4,33 +4,33 @@ The most common use of `octocatalog-diff` is to use `puppet` locally to compile
 
 In order to successfully use Puppet to compile catalogs:
 
-0. Puppet must be installed on the system.
+1. Puppet must be installed on the system.
 
-  It is the goal of `octocatalog-diff` to support Puppet version 3.8 and higher, installed via any means supported by Puppet. This includes the [All-In-One agent package](https://docs.puppet.com/puppet/4.0/reference/release_notes.html#all-in-one-packaging) or installed as a Ruby gem.
+    It is the goal of `octocatalog-diff` to support Puppet version 3.8 and higher, installed via any means supported by Puppet. This includes the [All-In-One agent package](https://docs.puppet.com/puppet/4.0/reference/release_notes.html#all-in-one-packaging) or installed as a Ruby gem.
 
-  By default, `octocatalog-diff` will look for the Puppet binary in several common system locations.
+    By default, `octocatalog-diff` will look for the Puppet binary in several common system locations.
 
-  For maximum reliability, you can specify the full path to the Puppet binary in the configuration file. For example:
+    For maximum reliability, you can specify the full path to the Puppet binary in the configuration file. For example:
 
-  ```
-  ##############################################################################################
-  # puppet_binary
-  #   This is the full path to the puppet binary on your system. If you don't specify this,
-  #   the tool will just run 'puppet' and hope to find it in your path.
-  ##############################################################################################
+    ```
+    ##############################################################################################
+    # puppet_binary
+    #   This is the full path to the puppet binary on your system. If you don't specify this,
+    #   the tool will just run 'puppet' and hope to find it in your path.
+    ##############################################################################################
 
-  # settings[:puppet_binary] = '/usr/bin/puppet'
-  settings[:puppet_binary] = '/opt/puppetlabs/puppet/bin/puppet'
-  ```
+    # settings[:puppet_binary] = '/usr/bin/puppet'
+    settings[:puppet_binary] = '/opt/puppetlabs/puppet/bin/puppet'
+    ```
 
-0. Applies if you are using [exported resources](https://docs.puppet.com/puppet/latest/reference/lang_exported.html) from PuppetDB (i.e., the octocatalog-diff `--storeconfigs` option enabled):
+1. Applies if you are using [exported resources](https://docs.puppet.com/puppet/latest/reference/lang_exported.html) from PuppetDB (i.e., the octocatalog-diff `--storeconfigs` option enabled):
 
-  Your Puppet installation must have the `puppetdb-termini` feature available. This feature may not be included by default with the Puppet agent package.
+    Your Puppet installation must have the `puppetdb-termini` feature available. This feature may not be included by default with the Puppet agent package.
 
-  Consult the [Connecting Puppet masters to PuppetDB](https://docs.puppet.com/puppetdb/latest/connect_puppet_master.html#step-1-install-plug-ins) documentation for instructions on installing the `puppetdb-termini` gem.
+    Consult the [Connecting Puppet masters to PuppetDB](https://docs.puppet.com/puppetdb/latest/connect_puppet_master.html#step-1-install-plug-ins) documentation for instructions on installing the `puppetdb-termini` gem.
 
-  :warning: Attention Mac OS users: the [documentation](https://docs.puppet.com/puppet/latest/reference/puppet_collections.html#os-x-systems) states:
+    :warning: Attention Mac OS users: the [documentation](https://docs.puppet.com/puppet/latest/reference/puppet_collections.html#os-x-systems) states:
 
-  > While the puppet-agent package is the only component of a Puppet Collection available on OS X, you can still use Puppet Collections to ensure the version of package-agent you install is compatible with the Puppet Collection powering your infrastructure.
+    > While the puppet-agent package is the only component of a Puppet Collection available on OS X, you can still use Puppet Collections to ensure the version of package-agent you install is compatible with the Puppet Collection powering your infrastructure.
 
-  Unfortunately this means that you won't be able to enable `--storeconfigs` with the All-In-One Puppet Agent on Mac OS X, unless you manually install a gem-packaged version of `puppetdb-terminus`. The procedure for this is beyond the scope of this documentation.
+    Unfortunately this means that you won't be able to enable `--storeconfigs` with the All-In-One Puppet Agent on Mac OS X, unless you manually install a gem-packaged version of `puppetdb-terminus`. The procedure for this is beyond the scope of this documentation.

data/doc/configuration-puppetdb.md

@@ -67,3 +67,11 @@ SSL support is enabled via any of the `--puppetdb-ssl-...` command line options
 - The CA certificate should be the public certificate of the CA that signed your PuppetDB server's certificate. This file can be found in `/etc/puppetlabs/puppetdb/ssl/ca.pem` on a PuppetDB server. Since this is a public certificate, it is safe (and recommended) to distribute this file to any clients that may connect to this PuppetDB instance.
 
 - The client keypair (key, certificate, and optionally password) should be generated individually for each client. You should NOT copy SSL keypairs from your PuppetDB server (or anywhere else) to your clients. If you are using `octocatalog-diff` on a system that is managed by Puppet, you may wish to use the same SSL credentials that the system uses to authenticate to Puppet. With recent versions of the Puppet agent, those certificates are found in `/etc/puppetlabs/puppet/ssl`.
+
+# Puppet Enterprise PuppetDB Package Inventory
+
+Puppet Enterprise customers have an optional package inventory feature which can be enabled. When this feature is enabled an inventory of all system packages
+is performed and uploaded as a fact which is then processed and stored independently of the normal Facter data in PuppetDB. Most environments won't need
+to replicate the package inventory facts for testing with Octocatalog-Diff but if you want the package inventory data (if present) to be included
+in the facts retrieved from PuppetDB by Octocatalog-Diff you should specify the `--puppetdb-package-inventory` flag. When enabled, this flag will instruct
+Octocatalog-Diff to retrieve any package data found for a node from PuppetDB and include it in the facts used during the Octocatalog-Diff compile.

data/doc/configuration.md

@@ -2,51 +2,51 @@
 
 `octocatalog-diff` may require configuration to work correctly with your Puppet setup.
 
-0. Download the [sample configuration file](https://raw.githubusercontent.com/github/octocatalog-diff/master/examples/octocatalog-diff.cfg.rb) and save it into one of the following directories.
+1. Download the [sample configuration file](https://raw.githubusercontent.com/github/octocatalog-diff/master/examples/octocatalog-diff.cfg.rb) and save it into one of the following directories.
 
-  - In the base directory of your Puppet repository checkout (i.e., your current working directory):
+    - In the base directory of your Puppet repository checkout (i.e., your current working directory):
 
-    ```
-    .octocatalog-diff.cfg.rb
-    ```
+      ```
+      .octocatalog-diff.cfg.rb
+      ```
 
-  - In your home directory:
+    - In your home directory:
 
-    ```
-    $HOME/.octocatalog-diff.cfg.rb
-    ```
+      ```
+      $HOME/.octocatalog-diff.cfg.rb
+      ```
 
-  - In one of the following system locations:
+    - In one of the following system locations:
 
-    ```
-    /usr/local/etc/octocatalog-diff.cfg.rb
-    /opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb
-    /etc/octocatalog-diff.cfg.rb
-    ```
+      ```
+      /usr/local/etc/octocatalog-diff.cfg.rb
+      /opt/puppetlabs/octocatalog-diff/octocatalog-diff.cfg.rb
+      /etc/octocatalog-diff.cfg.rb
+      ```
 
-  Note: If more than one of the above files is present, the first one found will be used (proceeding from top to bottom in that list). If you set an environment variable `OCTOCATALOG_DIFF_CONFIG_FILE` that will supersede all of the above paths, and allow you to specify the configuration file location however you wish.
+    Note: If more than one of the above files is present, the first one found will be used (proceeding from top to bottom in that list). If you set an environment variable `OCTOCATALOG_DIFF_CONFIG_FILE` that will supersede all of the above paths, and allow you to specify the configuration file location however you wish.
 
-0. Open the file in a text editor, and follow the comments within the file to guide yourself through configuration. The configuration file is pure ruby, allowing substantial flexibility in the configuration.
+1. Open the file in a text editor, and follow the comments within the file to guide yourself through configuration. The configuration file is pure ruby, allowing substantial flexibility in the configuration.
 
-  To be minimally functional, you will almost certainly need to define at least the following settings:
+    To be minimally functional, you will almost certainly need to define at least the following settings:
 
-  - `settings[:hiera_config]` as the absolute or relative path to your hiera configuration file
-  - `settings[:hiera_path_strip]` as the prefix to strip when munging the hiera configuration file
-  - `settings[:puppetdb_url]` as the URL to your PuppetDB instance so facts can be obtained
+    - `settings[:hiera_config]` as the absolute or relative path to your hiera configuration file
+    - `settings[:hiera_path_strip]` as the prefix to strip when munging the hiera configuration file
+    - `settings[:puppetdb_url]` as the URL to your PuppetDB instance so facts can be obtained
 
-  For more information on these settings:
+    For more information on these settings:
 
-  - [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md)
-  - [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md)
-  - [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md)
-  - [Configuring octocatalog-diff to use Puppet](/doc/configuration-puppet.md)
+    - [Configuring octocatalog-diff to use Hiera](/doc/configuration-hiera.md)
+    - [Configuring octocatalog-diff to use ENC](/doc/configuration-enc.md)
+    - [Configuring octocatalog-diff to use PuppetDB](/doc/configuration-puppetdb.md)
+    - [Configuring octocatalog-diff to use Puppet](/doc/configuration-puppet.md)
 
-0. Test the configuration, which will indicate the location of the configuration file and validate the contents thereof.
+1. Test the configuration, which will indicate the location of the configuration file and validate the contents thereof.
 
-  ```
-  octocatalog-diff --config-test
-  ```
+    ```
+    octocatalog-diff --config-test
+    ```
 
-  Note: If you [installed](/doc/installation.md) octocatalog-diff as a gem, the `octocatalog-diff` binary should be in your $PATH and the above command should work correctly. If you installed in a different way, you may need to provide the full path to where the `octocatalog-diff` binary was actually installed.
+    Note: If you [installed](/doc/installation.md) octocatalog-diff as a gem, the `octocatalog-diff` binary should be in your $PATH and the above command should work correctly. If you installed in a different way, you may need to provide the full path to where the `octocatalog-diff` binary was actually installed.
 
 Now that you have entered your configuration and confirmed proper reading of your configuration file, proceed to [Basic usage](/doc/basic.md) to see if it works!

data/doc/dev/api/v1/calls/catalog-diff.md

@@ -167,12 +167,16 @@ In this case, "owner", "notify", and "content" are nested under "parameters". In
 
   ```
   # Ignore all changes to the `owner` attribute of a file.
-  [ { type: Regexp.new('\AFile\z'), attr: Regexp.new("\Aparameters\fowner\z" } ]
+  [ { type: Regexp.new('\AFile\z'), attr: Regexp.new("\\Aparameters\fowner\\z" } ]
 
   # Ignore changes to `owner` or `group` for a file or an exec.
-  [ { type: Regexp.new('\A(File|Exec)\z'), attr: Regexp.new("\Aparameters\f(owner|group)\z" } ]
+  [ { type: Regexp.new('\A(File|Exec)\z'), attr: Regexp.new("\\Aparameters\f(owner|group)\\z" } ]
   ```
 
+When using regular expressions, `\f` (form feed character) is used to separate the structure (e.g. `parameters\fowner` refers to the `parameters` hash, `owner` key).
+
+:bulb: Note that `\A` in Ruby matches the beginning of the string and `\z` matches the end, but these are not actual characters. Therefore, if you are using `\A` or `\z` in double quotes (`"`), be sure to heed the examples above and write your expression like: `Regexp.new("\\Aparameters\fowner\\z")`.
+
 #### `:validate_references` (Array<String>, Optional)
 
 Invoke the [catalog validation](/doc/advanced-catalog-validation.md) feature to ensure resources targeted by `before`, `notify`, `require`, and/or `subscribe` exist in the catalog. If this parameter is not defined, no reference validation occurs.

data/doc/dev/api/v1/objects/diff.md

@@ -94,9 +94,9 @@ Returns the value of the resource from the new catalog.
     }
   }
 
-  # Demonstrates structure and old_value
+  # Demonstrates structure and new_value
   diff.structure #=> ['parameters', 'content']
-  diff.old_value #=> 'This is the NEW FILE!!!!!'
+  diff.new_value #=> 'This is the NEW FILE!!!!!'
   ```
 
 #### `#old_file` (String)
@@ -107,7 +107,7 @@ Note that this is a pass-through of information provided in the Puppet catalog,
 
 Note also that if the diff represents addition of a resource, this will return `nil`, because the resource does not exist in the old catalog.
 
-#### `#old_file` (String)
+#### `#old_line` (String)
 
 Returns the line number within the Puppet manifest giving rise to the resource as it exists in the old catalog. (See `#old_file` for the filename of the Puppet manifest.)