octocatalog-diff 0.5.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 373d19f3ac425f068b91f3fc3a32185375fbe13e
-  data.tar.gz: 344a4e7024b88ed9e1e75b60639269fa38cb5033
+  metadata.gz: 39148d81d6f446067f306d988b78a3544f381a47
+  data.tar.gz: e3212a9a0510be17e5bad0280baa66451cc3d77c
 SHA512:
-  metadata.gz: 50a77d5680032271a238a60ba1b33263a5f0797fdd2aad8bef18b643221e03b803b9c480e8b4da850eae74f2648aa6baf9dd6d6d6d430c257d6861a61efb78dc
-  data.tar.gz: 40f1df38c8b0f4ac1c7cd648bbf238b4b21f881291de9a8960c8773c9cf93339e1fddc597f4a4a954c3a0e85fde4979ee897610113b774a33ca371e914d7e429
+  metadata.gz: a2abdf4c5a2604c70938a50875dacc5af83e4ad4aeaa08ad2ac1e1c97a61c1cd4f47ad928cc361919993db5fb9fa5e70c76f29d172761e8c8bb8b3f68cf62e12
+  data.tar.gz: 2dbc74ab05804f35ae3106ccdbf494952f262110335e57c57f92f719387071289272fec6f6cea4db30b18b07d745b650a10708120ca9cda44e18a5e0ea3776fd

data/.version

@@ -1 +1 @@
-0.5.6
+0.6.0

data/doc/CHANGELOG.md

@@ -8,11 +8,29 @@
 </tr>
 </thead><tbody>
 <tr valign=top>
+<td>0.6.0</td>
+<td>2017-01-04</td>
+<td>
+<ul>
+<li><a href="https://github.com/github/octocatalog-diff/pull/45">#45</a>: Support for alternate environments in hiera configuration</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/43">#43</a>: Consider aliased resources in validation</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/39">#39</a>: Pass command line arguments to Puppet during catalog compilation</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/38">#38</a>: Preserve and select environments</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/37">#37</a>: Consistent sorting of equally weighted options</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/36">#36</a>: Validate before, notify, require, subscribe references</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/34">#34</a>: Allow bootstrap script to start with /</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/33">#33</a>: Double-escape facts passed to Puppet master</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/32">#32</a>: Rewrite hiera data directory for multiple backends</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/24">#24</a>: Support PuppetDB API v3</li>
+</ul>
+</td>
+</tr>
+<tr valign=top>
 <td>0.5.6</td>
 <td>2016-11-16</td>
 <td>
 <ul>
-<li><a href="https://github.com/github/octocatalog-diff/pull/20">https://github.com/github/octocatalog-diff/pull/20</a>: Use modulepath from environment.conf to inform lookup directories for <code>--compare-file-text</code> feature</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/20">#20</a>: Use modulepath from environment.conf to inform lookup directories for <code>--compare-file-text</code> feature</li>
 </ul>
 </td>
 </tr>
@@ -28,9 +46,9 @@ Unreleased internal version
 <td>2016-11-07</td>
 <td>
 <ul>
-<li><a href="https://github.com/github/octocatalog-diff/pull/16">https://github.com/github/octocatalog-diff/pull/16</a>: environment running <code>puppet --version</code></li>
-<li><a href="https://github.com/github/octocatalog-diff/pull/5">https://github.com/github/octocatalog-diff/pull/5</a>: bootstrap debugging</li>
-<li><a href="https://github.com/github/octocatalog-diff/pull/17">https://github.com/github/octocatalog-diff/pull/17</a>: hiera simplification and <code>--hiera-path</code> option</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/16">#16</a>: environment running <code>puppet --version</code></li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/5">#5</a>: bootstrap debugging</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/17">#17</a>: hiera simplification and <code>--hiera-path</code> option</li>
 </ul>
 </td>
 </tr>
@@ -39,7 +57,7 @@ Unreleased internal version
 <td>2016-10-31</td>
 <td>
 <ul>
-<li><a href="https://github.com/github/octocatalog-diff/pull/10">https://github.com/github/octocatalog-diff/pull/10</a>: facts terminus optimization</li>
+<li><a href="https://github.com/github/octocatalog-diff/pull/10">#10</a>: facts terminus optimization</li>
 </ul>
 </td>
 </tr>

data/doc/advanced-bootstrap.md

@@ -31,3 +31,28 @@ The [example configuration file](/examples/octocatalog-diff.cfg.rb) contains an
 # settings[:bootstrap_script] = '/etc/puppetlabs/repo-bootstrap.sh' # Absolute path
 # settings[:bootstrap_script] = 'script/bootstrap' # Relative path
 ```
+
+## Bootstrap environment
+
+When the bootstrap script runs, a limited set of environment variables are passed from the shell running octocatalog-diff. Only these variables are set:
+
+- `HOME`
+- `PATH`
+- `PWD` (set to the base directory of your Puppet checkout)
+- `BASEDIR` (as explicitly set with `--basedir` CLI option or `settings[:basedir]` setting)
+
+If you wish to set additional environment variables for your bootstrap script, you may do so via the `--bootstrap-environment VAR=value` command line flag, or by defining `settings[:bootstrap_environment] = { 'VAR' => 'value' }` in your configuration file.
+
+As an example, consider that your bootstrap script is written in Python, and needs the `PYTHONPATH` variable set to `/usr/local/lib/python-custom`. Even if this environment variable is set when octocatalog-diff is run, it will not be available to the bootstrap script. You may supply it via the command line:
+
+```
+octocatalog-diff --bootstrap-environment PYTHONPATH=/usr/local/lib/python-custom ...
+```
+
+Or you may specify it in your configuration file:
+
+```
+settings[:bootstrap_environment] = {
+  'PYTHONPATH' => '/usr/local/lib/python-custom'
+}
+```

data/doc/advanced-catalog-validation.md

@@ -0,0 +1,41 @@
+# Catalog validation
+
+`octocatalog-diff` contains additional functionality to validate catalogs, based on configurable criteria.
+
+Catalog validation features include:
+
+- Validate references: Ensure resources targeted by `before`, `notify`, `require`, and/or `subscribe` exist in the catalog
+
+## Validate references
+
+`octocatalog-diff` includes the ability to validate references by ensuring resources targeted by `before`, `notify`, `require`, and/or `subscribe` parameters also exist in the catalog.
+
+Consider the following Puppet code:
+
+```
+file { '/usr/local/bin/some-script.sh':
+  source => 'puppet:///modules/test/usr/local/bin/some-script.sh',
+  notify => Exec['execute /usr/local/bin/some-script.sh'],
+}
+```
+
+The catalog for this code would build, whether or not the `exec { 'execute /usr/local/bin/some-script.sh': ... }` resource was part of the catalog. However, when the catalog is applied on the Puppet agent, it would fail if this resource is missing.
+
+With the `--validate-references` command line flag (or the `settings[:validate_references]` [configuration setting](/doc/configuration.md)), you can instruct `octocatalog-diff` to confirm that any resource targeted by a `before`, `notify`, `require`, and `subscribe` parameter actually exists. If the resource is missing from the catalog, an error will be raised, just as if the catalog failed to compile.
+
+The command line argument is demonstrated here:
+
+```
+# Validate all references: before,notify,require,subscribe
+octocatalog-diff ... --validate-references before,notify,require,subscribe
+
+# Validate some references: only before and require
+octocatalog-diff ... --validate-references before,require
+
+# Validate no references
+octocatalog-diff ... --no-validate-references
+```
+
+By default, no references are validated.
+
+Note as well, when using `octocatalog-diff` to compare two catalogs, the references in the "from" catalog are not checked. The reason for this design decision is as follows: the "from" catalog is generally what is considered to be stable and is perhaps already deployed, so it adds no value (and perhaps inhibits the ability to develop further) if `octocatalog-diff` fails just because references in the "from" catalog are broken.

data/doc/advanced-environments.md

@@ -0,0 +1,93 @@
+# Environment setup
+
+When building a catalog, the default behavior of `octocatalog-diff` is to:
+
+1. Create a temporary directory
+2. Create a symlink from `<temporary directory>/environments/production` to the checkout of your code
+3. Run Puppet using `environment=production`
+
+If you are using environment names to control the behavior of Puppet, this default behavior may not be suitable. In that case you can invoke the alternate behavior: preserving environments.
+
+## Command line options
+
+### Preserving the environments
+
+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:
+
+  - `environments`
+  - `manifests`
+  - `modules`
+
+3. 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.
+
+### Changing the environment
+
+If you wish to use an environment name other than `production` you can use the `--environment <environment_name>` command line option. This will set the environment for both the `to` and `from` compiles.
+
+```
+octocatalog-diff ... --preserve-environments --environment some-env-name
+```
+
+If you need to specify different environments for the `to` and `from` compiles, you can use `--to-environment <environment_name>` and `--from-environment <environment_name>`.
+
+```
+octocatalog-diff ... --preserve-environments --to-environment first-environment --from-environment second-environment
+```
+
+### Controlling symlinks that are created
+
+Within the temporary directory, the `environments` symlink will always be created.
+
+By default, `manifests` and `modules` will also be created from the temporary directory to the corresponding directories in your Puppet code base. If you need to customize the symlinks that are created, you can use the `--create-symlinks <dir1>,<dir2>,...` to list the symlinks that you need.
+
+For example, if you have some code stored in a directory called `modules` and more code stored in a directory called `site`, you could do the following to create the symlinks as desired:
+
+```
+octocatalog-diff ... --preserve-environments --create-symlinks manifests,modules,site
+```
+
+## Examples
+
+Consider that your Puppet code base is organized as follows:
+
+```
+- /opt/puppet
+  - environments
+    - old
+      - environment.conf
+      - manifests
+        - site.pp
+      - modules
+        - module_zero
+    - new
+      - environment.conf
+      - manifests
+        - site.pp
+      - modules
+        - module_zero
+  - modules
+    - module_one
+    - module_two
+  - site
+    - module_three
+    - module_four
+```
+
+To calculate the difference between the "old" and "new" environment, you could use:
+
+```
+octocatalog-diff \
+  --bootstrapped-from-dir /opt/puppet \
+  --bootstrapped-to-dir /opt/puppet \
+  --preserve-environments \
+  --from-environment old \
+  --to-environment new \
+  --create-symlinks modules,site
+```
+
+(Note that `--bootstrapped-from-dir` and `--bootstrapped-to-dir` are used to specify the directory path to your code, and `-t` and `-f` are not used. That's because the difference in the catalog is derived from the environment used, and not the branch from a git repository.)

data/doc/advanced-hiera-path-stripping.md

@@ -37,3 +37,5 @@ bin/octocatalog-diff --hiera-config hiera.yaml --hiera-path-strip /etc/puppetlab
 :yaml:
   :datadir: /var/tmp/puppet-compile-dir-92347829847/environments/%{environment}/hieradata
 ```
+
+:warning: Be sure that you do NOT include a trailing slash on `--hiera-path-strip` or `settings[:hiera_path_strip]`.

data/doc/advanced.md

@@ -21,6 +21,8 @@ See also:
 - [Overriding facts](/doc/advanced-override-facts.md)
 - [Puppet Enterprise node classification service](/doc/advanced-pe-enc.md)
 - [Using `octocatalog-diff` without git](/doc/advanced-using-without-git.md)
+- [Catalog validation](/doc/advanced-catalog-validation.md)
+- [Environment setup](/doc/advanced-environment.md)
 
 ### Controlling output
 

data/doc/configuration-enc.md

@@ -67,3 +67,37 @@ For example, when compiling the catalog for `some-node.github.net`, Puppet will
   ```
 
 Sometimes the ENC script requires credentials or makes other assumptions about the system on which it is running. To be able to run the ENC script on systems other than your Puppet master, you will need to ensure that any such credentials are supplied and other assumptions are met.
+
+## Environment
+
+When the ENC is executed, the following environment variables are set to match the environment of the shell in which octocatalog-diff executes:
+
+- `HOME`
+- `PATH`
+- `PWD` (set to the temporary directory as previously described)
+
+No other environment variables are passed from the shell. If you wish to pass additional environment variables, you must explicitly list them with the `--pass-env-vars` CLI flag or `settings[:pass_env_vars]` array in your configuration file.
+
+As an example, consider that your ENC is written in Python, and needs the `PYTHONPATH` variable set to `/usr/local/lib/python-custom`. Even if this environment variable is set when octocatalog-diff is run, it will not be available to the ENC script. You may pass the variable via the command line:
+
+```
+octocatalog-diff --pass-env-vars PYTHONPATH ...
+```
+
+Or you may specify it in your configuration file:
+
+```
+settings[:pass_env_vars] = [ 'PYTHONPATH' ]
+```
+
+If you wish to specify multiple environment variables to pass:
+
+```
+octocatalog-diff --pass-env-vars PYTHONPATH,SECONDVAR,THIRDVAR ...
+```
+
+or
+
+```
+settings[:pass_env_vars] = [ 'PYTHONPATH', 'SECONDVAR', 'THIRDVAR' ]
+```

data/doc/dev/releasing.md

@@ -2,8 +2,47 @@
 
 The project maintainers are responsible for bumping the version number, regenerating auto-generated documentation, tagging the release, and uploading to rubygems.
 
-0. Ensure that all changes have been merged to master.
+## Local testing
+
+To test the new version of `octocatalog-diff` in the Puppet repository:
+
+0. In the Puppet checkout, start a new branch based off master.
+0. In the `octocatalog-diff` checkout:
+  - Ensure that the desired branch is checked out.
+  - Choose a unique internal version number which has never been used in CI. A good guideline is that if you're planning to release a version `0.6.0` then for these tests, use `0.6.0a`, `0.6.0b`, ...
+  - Build the gem using your internal version number:
+
+    ```
+    OCTOCATALOG_DIFF_VERSION=0.6.0a rake gem:force-build
+    ```
+  - Run the task to install the gem into your Puppet checkout:
+
+    ```
+    OCTOCATALOG_DIFF_VERSION=0.6.0a rake gem:localinstall
+    ```
+
+0. Back in the Puppet checkout, ensure that the changes are as expected (updates to Gemfile / Gemfile.lock, addition of new gem). Push the change and build appropriate CI job(s) to validate the changes.
+
+## Merging
+
 0. If necessary, complete a Pull Request to update the [version file](/.version).
+0. If necessary, auto-generate the build documentation.
+
+  ```
+  rake doc:build
+  ```
+
+0. Ensure that CI tests are all passing.
+0. Merge and delete the branch.
+
+## Releasing
+
+Generally, a new release will correspond to a merge to master of one or more Pull Requests.
+
+0. Ensure that all changes associated with the release have been merged to master.
+  - Merge all Pull Requests associated with release.
+  - If necessary, complete a Pull Request to update the [change log](/doc/CHANGELOG.md).
+  - If necessary (for significant changes), complete a Pull Request to update the top-level README file.
 0. Ensure the the master branch is checked out on your system.
 0. Run the release procedure:
 
@@ -13,7 +52,6 @@ The project maintainers are responsible for bumping the version number, regenera
 
 This rake task handles the following:
 
-- Auto-generates the [options reference](/doc/optionsref.md) (`rake doc:build`)
 - Build the gem file (`rake gem:build`)
 - Tag the release in the repository (`rake gem:tag`)
 - Upload the gem file to rubygems (`rake gem:push`)

data/doc/dev/run-from-branch.md

@@ -0,0 +1,62 @@
+# Running octocatalog-diff from a branch
+
+When we are assisting with troubleshooting, or implementing a feature you've requested, we may ask you to run `octocatalog-diff` from a non-master branch to try it out.
+
+This document is intended for people who may not be familiar with git, GitHub, and/or ruby. If you already know how to do this in another way, feel free!
+
+## Installation
+
+1. Determine the branch name. If there's an open Pull Request, you can see the branch name near the top of the page.
+
+  ![Pull Request branch](/doc/images/pull-request-identify-branch.png)
+
+2. Clone the `octocatalog-diff` repository in your home directory. From the command line:
+
+  ```
+  cd $HOME
+  git clone https://github.com/github/octocatalog-diff.git
+  ```
+
+3. Change into the directory created by your checkout:
+
+  ```
+  cd $HOME/octocatalog-diff
+  ```
+
+4. Check out the branch you wish to use, filling in the branch name you determined in the first step:
+
+  ```
+  git checkout BRANCH_NAME_FROM_STEP_1
+  ```
+
+5. Bootstrap the repository to pull in dependencies:
+
+  ```
+  ./script/bootstrap
+  ```
+
+6. Optional but recommended - run the test suite:
+
+  ```
+  rake
+  ```
+
+## Use
+
+Now that you have `octocatalog-diff` checked out and bootstrapped, it's time to use it.
+
+We've created a wrapper script to make this easier for you.
+
+1. Change directories to the location where you ordinarily run `octocatalog-diff` (for example: in your Puppet repository).
+
+    ```
+    cd /etc/puppetlabs/code
+    ```
+
+2. Run the `script/octocatalog-diff-wrapper` script from *this* checkout. For example, if you checked out `octocatalog-diff` to your home directory, you could use:
+
+    ```
+    $HOME/octocatalog-diff/script/octocatalog-diff-wrapper <options>
+    ```
+
+:warning: Note: If you are requesting our help, please use the debug option (`-d`) to display debugging information.

data/doc/installation.md

@@ -47,3 +47,9 @@ To install from source, you'll need a git client and internet access.
   Note: If tests fail on your machine with a clean checkout of the master branch, we would definitely appreciate if you would report it. Please [open an issue](https://github.com/github/octocatalog-diff/issues/new) with the output and some information about your system (e.g. OS, ruby version, etc.) to let us know.
 
 Once the code is downloaded and bootstrapped, please proceed to [Configuration](/doc/configuration.md).
+
+## Running from an alternate branch
+
+We have prepared specific instructions for running `octocatalog-diff` from a non-master branch, for testing changes that may be requested by the developers.
+
+- [Running octocatalog-diff from a branch](/doc/dev/run-from-branch.md)

data/doc/optionsref.md

@@ -47,6 +47,8 @@ Usage: octocatalog-diff [command line options]
         --ignore-attr "attr1,attr2,..."
                                      Attributes to ignore
         --[no-]display-source        Show source file and line for each difference
+        --[no-]validate-references "before,require,subscribe,notify"
+                                     References to validate
         --[no-]compare-file-text     Compare text, not source location, of file resources
         --[no-]storeconfigs          Enable integration with puppetdb for collected resources
         --retry-failed-catalog N     Retry building a failed catalog N times
@@ -64,28 +66,29 @@ Usage: octocatalog-diff [command line options]
         --[no-]display-datatype-changes
                                      Display changes in data type even when strings match
         --[no-]catalog-only          Only compile the catalog for the "to" branch but do not diff
+        --[no-]from-puppetdb         Pull "from" catalog from PuppetDB instead of compiling
+        --[no-]parallel              Enable or disable parallel processing
         --puppet-binary STRING       Full path to puppet binary globally
         --to-puppet-binary STRING    Full path to puppet binary for the to branch
         --from-puppet-binary STRING  Full path to puppet binary for the from branch
-        --[no-]from-puppetdb         Pull "from" catalog from PuppetDB instead of compiling
-        --[no-]parallel              Enable or disable parallel processing
+        --facts-terminus STRING      Facts terminus: one of yaml, facter
         --puppetdb-ssl-ca FILENAME   CA certificate that signed the PuppetDB certificate
+        --puppetdb-ssl-client-password PASSWORD
+                                     Password for SSL client key to connect to PuppetDB
         --puppetdb-ssl-client-cert FILENAME
                                      SSL client certificate to connect to PuppetDB
+        --puppetdb-ssl-client-key FILENAME
+                                     SSL client key to connect to PuppetDB
         --puppetdb-ssl-client-password-file FILENAME
                                      Read password for SSL client key from a file
-        --puppetdb-ssl-client-password PASSWORD
-                                     Password for SSL client key to connect to PuppetDB
-        --facts-terminus STRING      Facts terminus: one of yaml, facter
         --puppetdb-url URL           PuppetDB base URL
-        --puppetdb-ssl-client-key FILENAME
-                                     SSL client key to connect to PuppetDB
-        --puppet-master-ssl-client-key STRING
-                                     Full path to key file for SSL client auth to Puppet Master globally
-        --to-puppet-master-ssl-client-key STRING
-                                     Full path to key file for SSL client auth to Puppet Master for the to branch
-        --from-puppet-master-ssl-client-key STRING
-                                     Full path to key file for SSL client auth to Puppet Master for the from branch
+        --puppetdb-api-version N     Version of PuppetDB API (3 or 4)
+        --fact-override STRING1[,STRING2[,...]]
+                                     Override fact globally
+        --to-fact-override STRING1[,STRING2[,...]]
+                                     Override fact for the to branch
+        --from-fact-override STRING1[,STRING2[,...]]
+                                     Override fact for the from branch
         --puppet-master STRING       Hostname or Hostname:PortNumber for Puppet Master globally
         --to-puppet-master STRING    Hostname or Hostname:PortNumber for Puppet Master for the to branch
         --from-puppet-master STRING  Hostname or Hostname:PortNumber for Puppet Master for the from branch
@@ -107,15 +110,15 @@ Usage: octocatalog-diff [command line options]
                                      Full path to certificate file for SSL client auth to Puppet Master for the to branch
         --from-puppet-master-ssl-client-cert STRING
                                      Full path to certificate file for SSL client auth to Puppet Master for the from branch
-        --fact-override STRING1[,STRING2[,...]]
-                                     Override fact globally
-        --to-fact-override STRING1[,STRING2[,...]]
-                                     Override fact for the to branch
-        --from-fact-override STRING1[,STRING2[,...]]
-                                     Override fact for the from branch
+        --puppet-master-ssl-client-key STRING
+                                     Full path to key file for SSL client auth to Puppet Master globally
+        --to-puppet-master-ssl-client-key STRING
+                                     Full path to key file for SSL client auth to Puppet Master for the to branch
+        --from-puppet-master-ssl-client-key STRING
+                                     Full path to key file for SSL client auth to Puppet Master for the from branch
         --pe-enc-url URL             Base URL for Puppet Enterprise ENC endpoint
-        --pe-enc-token-file PATH     Path containing token for PE node classifier, relative or absolute
         --pe-enc-token TOKEN         Token to access the Puppet Enterprise ENC API
+        --pe-enc-token-file PATH     Path containing token for PE node classifier, relative or absolute
         --pe-enc-ssl-ca FILENAME     CA certificate that signed the ENC API certificate
         --pe-enc-ssl-client-cert FILENAME
                                      SSL client certificate to connect to PE ENC
@@ -124,10 +127,26 @@ Usage: octocatalog-diff [command line options]
         --no-ignore-tags             Disable ignoring based on tags
         --ignore-tags STRING1[,STRING2[,...]]
                                      Specify tags to ignore
-        --[no-]suppress-absent-file-details
-                                     Suppress certain attributes of absent files
+        --[no-]preserve-environments Enable or disable environment preservation
+        --environment STRING         Environment for catalog compilation globally
+        --to-environment STRING      Environment for catalog compilation for the to branch
+        --from-environment STRING    Environment for catalog compilation for the from branch
+        --create-symlinks STRING1[,STRING2[,...]]
+                                     Symlinks to create globally
+        --to-create-symlinks STRING1[,STRING2[,...]]
+                                     Symlinks to create for the to branch
+        --from-create-symlinks STRING1[,STRING2[,...]]
+                                     Symlinks to create for the from branch
+        --command-line STRING1[,STRING2[,...]]
+                                     Command line arguments globally
+        --to-command-line STRING1[,STRING2[,...]]
+                                     Command line arguments for the to branch
+        --from-command-line STRING1[,STRING2[,...]]
+                                     Command line arguments for the from branch
         --pass-env-vars VAR1[,VAR2[,...]]
                                      Environment variables to pass
+        --[no-]suppress-absent-file-details
+                                     Suppress certain attributes of absent files
 
 ```
 
@@ -828,6 +847,34 @@ https://your-pe-console-server:4433/classifier-api (<a href="../lib/octocatalog-
     </td>
   </tr>
 
+  <tr>
+    <td valign=top>
+      <pre><code>--preserve-environments
+--no-preserve-environments </code></pre>
+    </td>
+    <td valign=top>
+      Enable or disable environment preservation
+    </td>
+    <td valign=top>
+      Preserve the `environments` directory from the repository when compiling the catalog. Likely
+requires some combination of `--to-environment`, `--from-environment`, and/or `--create-symlinks`
+to work correctly. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/preserve_environments.rb">preserve_environments.rb</a>)
+    </td>
+  </tr>
+
+  <tr>
+    <td valign=top>
+      <pre><code>--puppetdb-api-version N</code></pre>
+    </td>
+    <td valign=top>
+      Version of PuppetDB API (3 or 4)
+    </td>
+    <td valign=top>
+      Specify the API version to use for the PuppetDB. The current values supported are '3' or '4', and '4' is
+the default. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/puppetdb_api_version.rb">puppetdb_api_version.rb</a>)
+    </td>
+  </tr>
+
   <tr>
     <td valign=top>
       <pre><code>--puppetdb-ssl-ca FILENAME</code></pre>
@@ -1014,4 +1061,19 @@ These files must exist and be in Puppet catalog format. (<a href="../lib/octocat
     </td>
   </tr>
 
+  <tr>
+    <td valign=top>
+      <pre><code>--validate-references
+--no-validate-references </code></pre>
+    </td>
+    <td valign=top>
+      References to validate
+    </td>
+    <td valign=top>
+      Confirm that each `before`, `require`, `subscribe`, and/or `notify` points to a valid
+resource in the catalog. This value should be specified as an array of which of these
+parameters are to be checked. (<a href="../lib/octocatalog-diff/catalog-diff/cli/options/validate_references.rb">validate_references.rb</a>)
+    </td>
+  </tr>
+
 </table>